Home

Welcome to the Emporia Trading Platform Wiki

Emporia is an enterprise-grade, distributed stock trading platform built with Java 21, Spring Boot 4.0.7, React 19, Apache Kafka, gRPC, and PostgreSQL.

Its deployable boundaries align with business capabilities: static data, user preferences, market data, order management and portfolio tracking are independent, loosely coupled microservices. Execution routing is deliberately not one of them — it runs in-process inside order management, because an order crossing a process boundary on its way to a venue sets a latency floor no tuning inside either side can lower.

---

📈 Financial & Business Logic

Section	Description
📖 Trading Terminology Glossary	Financial glossary defining order types, market microstructure (BBO, L1/L2), SOR, VWAP, cost basis, and risk terms.
📜 Order Lifecycle & Validation	Order types (MARKET, LIMIT, STOP), tick size/lot size validation, state machine transitions, and late fill accounting.
🧠 Order Routing & SOR	Smart Order Routing (SOR) NBBO matching algorithms, multi-venue order splitting, and VWAP algorithmic time-slicing.
📊 Market Data & Pricing	Level-1 (BBO) & Level-2 order book depth, Price-Time priority matching, micro-price formulas, and SSE/gRPC streaming.
💼 Portfolio & Risk Management	Long/short position tracking, weighted average cost basis, Realized vs Unrealized Mark-to-Market PnL, and pre-trade risk controls.

---

🚀 System Architecture & Specifications

Section	Description
📐 Architecture & Order Flow	System architecture diagrams, microservice port matrix, REST vs Kafka EDA, database ownership, DSL-JSON WebFlux codecs, and 50,000 TPS architecture.
📦 Microservices Overview	Deep-dive overview into all 7 microservices, Spring Cloud API Gateway, OAuth2 authentication server, and React 19 Trading UI.
⚡ No Blocking DB on Hot Path	Why the order hot path makes no blocking PostgreSQL call, the five mechanisms behind it, and the three constraints accepted in exchange.
⚡ Exchange-Core Integration	High-performance LMAX Disruptor matching engine integration, Direct In-Memory Hot-Path Ingress, and Zero-GC primitive long math for fixed-point arithmetic.
🧩 Design Patterns	Catalog of architectural (CQRS, EDA, SAGA) and software design patterns (Strategy, State Machine, Observer, Facade, Decorator).
🧪 Testing & Verification	91.95% JaCoCo coverage, Testcontainers PostgreSQL concurrency tests, Fray controlled thread scheduling, and 50,000 TPS high-load matrix.
💾 WAL Crash Recovery Verification	Step-by-step kill -9 verification of the order-management write-ahead log: zero order loss proof and automated crash runbook.
🛠️ Deployment & Operations	Prerequisites, Docker Compose setup, Maven multi-module build steps, and environment configuration.

---

⚙️ Microservices Deep-Dives

Section	Description
📋 Static Data Service	Instrument listing directory, tick/lot size constraints, exchange MICs (XNAS, XNYS, XOSR), Alpaca asset master importer.
📊 Market Data Service	Real-time quote ingestion, simulated / alpaca-iex / fix-simulator drivers, XOSR composite books, SSE & gRPC streams.
⚙️ Order Management Service (OMS)	Deep-dive into OMS architecture, in-process REST/Aeron command intake, OrderCommandHandler, ExecutionCommandHandler, state machine, and idempotency logic.
🎯 Execution Routing	Deep-dive into the execution routing engine — DMA, SMART (SOR NBBO selector), VWAP time-slicer, venue gateways — which runs in-process inside the OMS.
💼 Portfolio Service	Internal balance ledger, risk seeding, exchange snapshot PUT receipt contract, Async User Balance Netting (200x DB load reduction), SHA-256 idempotency.

---

📊 Core Architecture Overview

flowchart TD
    Browser["React Trading UI :3001"] -->|OIDC + PKCE / Bearer token| Gateway["Spring Cloud Gateway :8082"]
    Gateway --> Auth["Authentication :9000"]
    Gateway --> Static["Static Data :8081"]
    Gateway --> Preferences["User Preferences :8083"]
    Gateway --> Market["Market Data :8084"]
    Gateway --> Orders["Order Management :8086"]
    Gateway --> Portfolio
    ExchangeCore["Exchange-Core Simulation"] -->|risk seed + durable snapshots| Portfolio["Portfolio :8088"]
    ExchangeCore -->|bearer token| Auth

    Preferences -->|listing snapshots| Static
    Market -->|listing snapshots| Static
    Market -->|client credentials| Auth
    Fix["FIX Simulator gRPC Sources"] -->|incremental books| Market
    Alpaca["Alpaca IEX"] -->|snapshot + WebSocket| Market
    Orders -->|validate listing| Static

    Orders -->|"order domain events, ShardedOrderDispatcher"| Execution["Execution routing<br/>(in-process inside OMS)"]
    Execution -->|"SMART/VWAP child CREATE, in-process"| Orders
    Execution -->|"FILL / REJECT / venue CANCEL, in-process"| Orders
    Execution -->|client credentials| Auth
    Execution -->|same-instrument listings| Static
    Execution -->|venue quotes| Market

    Auth --> AuthDb[("PostgreSQL\nemporia_authentication")]
    Static --> StaticDb[("PostgreSQL\nemporia_static_data")]
    Preferences --> PreferencesDb[("PostgreSQL\nemporia_client_config")]
    Orders --> OrderDb[("PostgreSQL\nemporia_order_data")]
    Portfolio --> PortfolioDb[("PostgreSQL\nemporia_portfolio")]

Loading