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 strictly align with business capabilities: static data, user preferences, market data, order command handling, order management, execution routing, and portfolio tracking are all managed by independent, loosely coupled microservices.

---

📈 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.

---

🚀 Architecture & Technical Specifications

Section	Description
📐 Architecture & Order Flow	System architecture diagrams, microservice port matrix, REST vs Kafka EDA, database ownership, and end-to-end order lifecycle.
📋 Static Data Service	Instrument listing directory, tick/lot size constraints, exchange MICs (XNAS, XNYS, XOSR), Alpaca importer.
📊 Market Data Service	Real-time quote ingestion, simulated / alpaca-iex / fix-simulator drivers, XOSR composite books, SSE & gRPC streams.
📨 Order Command Service	Command intake REST APIs, static data validation, KafkaCommandGateway, and asynchronous result correlation.
⚙️ Order Management Service (OMS)	Deep-dive into OMS architecture, OrderCommandHandler, ExecutionCommandHandler, state machine, and idempotency logic.
🎯 Execution Service	Deep-dive into execution routing engine, DMA, SMART (SOR NBBO selector), VWAP time-slicer, and venue gateways.
💼 Portfolio Service	Internal balance ledger, risk seeding, exchange snapshot PUT receipt contract, SHA-256 idempotency, pessimistic locks.
🧩 Design Patterns	Catalog of architectural (CQRS, EDA, SAGA) and software design patterns (Strategy, State Machine, Observer, Facade, Decorator).
📦 Microservices Overview	Deep-dive into all 9 microservices, API Gateway, OAuth2 Authorisation server, and React 19 Trading UI.
⚡ Exchange-Core Integration	High-performance LMAX Disruptor matching engine integration, lock-free ring buffers, and risk seeding.
🧪 Testing & Verification	91.95% JaCoCo coverage, Testcontainers PostgreSQL concurrency tests, Fray controlled thread scheduling, and PMD static code analysis.
🛠️ Deployment & Operations	Prerequisites, Docker Compose setup, Maven multi-module build steps, and environment configuration.

---

📊 Core Architecture Overview

flowchart TD
    Browser["React Trading UI :3001"] -->|OIDC + PKCE / Bearer token| Gateway["Spring Cloud Gateway :8082"]
    Gateway --> Auth["Authorisation Service :9000"]
    Gateway --> Static["Static Data Service :8081"]
    Gateway --> Preferences["User Preferences :8083"]
    Gateway --> Market["Market Data Service :8084"]
    Gateway --> OrderCommands["Order Command Service :8085"]
    Gateway --> Orders["Order Management Service :8086"]
    Execution["Execution Service :8087"] -->|client credentials| Auth
    ExchangeCore["Exchange-Core Simulation"] -->|risk seed + durable snapshots| Portfolio["Portfolio Service :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
    OrderCommands -->|validate listing| Static

    OrderCommands -->|CREATE / MODIFY / CANCEL| Commands[["emporia.order.commands.v1"]]
    Commands --> Orders
    Orders -->|correlated outcome| Results[["emporia.order.results.v1"]]
    Results --> OrderCommands
    Orders -->|immutable state events| OrderLog[["emporia.orders.v1"]]
    OrderLog --> Execution
    Execution -->|FILL / REJECT / venue CANCEL| ExecutionCommands[["emporia.execution.commands.v1"]]
    ExecutionCommands --> Orders
    Execution -->|recover active parents and children| Orders
    Execution -->|same-instrument listings| Static
    Execution -->|venue quotes| Market

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

Loading