Spaces:

RayMelius
/

EuNEx

Sleeping

App Files Files Community

EuNEx / docs /developers-guide.md

RayMelius

docs: Update README and developers guide for v0.9.5

902dc22 7 days ago

preview code

raw

history blame contribute delete

85.8 kB

EuNEx Developers Guide

Version 0.9.5 | Euronext Optiq-Modeled Exchange Simulator

Overview
Architecture
Optiq Naming Alignment
Actor Topology
Data Flow
Core Components
Event System
Order Book & Matching
Recovery & IACA
Kafka Bus
FIX Protocol Gateway
Clearing House
AI Trading Members
Market Simulation
AI Market Analyst
Developer Message Flow Visualizer
Engine Mode Switch
Project Structure
Build & Test
Configuration
Extending EuNEx

1. Overview

EuNEx (Euronext Exchange Simulator) is a C++20 actor-based matching engine that mirrors the Euronext Optiq production architecture. It implements the full order lifecycle: entry, validation, matching, market data dissemination, trade clearing, and FIX protocol connectivity.

  ┌─────────────────────────────────────────────────────────────────────┐
  │                         EuNEx v0.9.5                                │
  │                                                                     │
  │   FIX 4.4 Clients ──► OEG ──► ME (per symbol) ──► MDG             │
  │                         │                    │                       │
  │                         ◄── Exec Reports ◄───┘                      │
  │                                              │                      │
  │                                         Clearing House              │
  │                                              │                      │
  │                                         AI Traders (x10)            │
  └─────────────────────────────────────────────────────────────────────┘

Key design principles:

Actor-per-core isolation (no shared mutable state in the hot path)
Lock-free Event::Pipe for cross-actor communication
Fixed-point pricing (8 decimal places, PRICE_SCALE = 10^8)
Price-time priority matching with multi-level sweep
Master/Mirror recovery gating for high availability

2. Architecture

High-Level System Diagram

 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                           EXTERNAL CLIENTS                                  │
 │                  Browser / FIX 4.4 / Direct API / REST                      │
 └──────┬──────────────────┬───────────────────────────────┬───────────────────┘
        │                  │                               │
     HTTP :7860         TCP :9001                    Direct API
        │                  │                               │
 ╔══════╪══════════════════════════════════════════════════════════════════════╗
 ║  PRESENTATION LAYER (Python / nginx)                                       ║
 ║                                                                             ║
 ║  ┌──────────────────────┐    ┌──────────────────────┐                      ║
 ║  │  nginx (:7860)       │    │                      │                      ║
 ║  │  reverse proxy       │    │                      │                      ║
 ║  │  /       → :8090     │    │                      │                      ║
 ║  │  /ch/    → :8091     │    │                      │                      ║
 ║  └───┬──────────┬───────┘    │                      │                      ║
 ║      │          │            │                      │                      ║
 ║      ▼          ▼            │                      │                      ║
 ║  ┌──────────┐ ┌──────────┐  │                      │                      ║
 ║  │Dashboard │ │Clearing  │  │                      │                      ║
 ║  │ (:8090)  │ │House UI  │  │                      │                      ║
 ║  │          │ │ (:8091)  │  │                      │                      ║
 ║  │ Order    │ │          │  │                      │                      ║
 ║  │ Book     │ │ Leader-  │  │                      │                      ║
 ║  │ Charts   │ │ board    │  │                      │                      ║
 ║  │ OHLCV    │ │ Holdings │  │                      │                      ║
 ║  │ SSE      │ │ P&L      │  │                      │                      ║
 ║  └────┬─────┘ └────┬─────┘  │                      │                      ║
 ║       │            │         │                      │                      ║
 ║   getSnapshot() getLeaderboard()                    │                      ║
 ║   getRecentTrades() (thread-safe reads)             │                      ║
 ╚═══════╪════════════╪════════════════════════════════════════════════════════╝
         │            │        │                               │
         └────────────┴────────┘                               │
                      │                                        │
               Thread-safe C++ API                      TCP :9001
                      │                                        │
 ╔════════════════════╪════════════════════════════════════╪═══════════════════╗
 ║  CORE 0 — Gateway                                                          ║
 ║  ┌──────────────────────────┐    ┌──────────────────────────┐              ║
 ║  │   FIXAcceptorActor       │◄───┤     OEGActor        ◄────┤              ║
 ║  │                          │───►│                          │              ║
 ║  │  • TCP accept loop       │    │  • Session validation    │              ║
 ║  │  • FIX 4.4 parse/build   │    │  • Symbol routing        │              ║
 ║  │  • Logon/Logout/HB       │    │  • Exec report fanout    │              ║
 ║  │  • D, F, G → Events      │    │  • Cancel, Modify        │              ║
 ║  └──────────────────────────┘    └──────────┬───────────────┘              ║
 ╚═════════════════════════════════════════════╪═══════════════════════════════╝
                                               │ NewOrderEvent
                                               │ CancelOrderEvent
                                               │ ModifyOrderEvent
                                               │ (Event::Pipe)
                                               ▼
 ╔═════════════════════════════════════════════════════════════════════════════╗
 ║  CORE 1 — Matching Engine (one MECoreActor per symbol)                     ║
 ║                                                                             ║
 ║  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐   ║
 ║  │ MECoreActor   │ │ MECoreActor   │ │ MECoreActor   │ │ MECoreActor   │   ║
 ║  │ AAPL (sym=1)  │ │ MSFT (sym=2)  │ │ GOOGL (sym=3) │ │ EURO50 (sym=4)│   ║
 ║  │               │ │               │ │               │ │               │   ║
 ║  │  ┌─────────┐  │ │  ┌─────────┐  │ │  ┌─────────┐  │ │  ┌─────────┐  │   ║
 ║  │  │  Book   │  │ │  │  Book   │  │ │  │  Book   │  │ │  │  Book   │  │   ║
 ║  │  │ (bids)  │  │ │  │ (bids)  │  │ │  │ (bids)  │  │ │  │ (bids)  │  │   ║
 ║  │  │ (asks)  │  │ │  │ (asks)  │  │ │  │ (asks)  │  │ │  │ (asks)  │  │   ║
 ║  │  └─────────┘  │ │  └─────────┘  │ │  └─────────┘  │ │  └─────────┘  │   ║
 ║  └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘   ║
 ║          │                 │                 │                 │             ║
 ║          └────────┬────────┴────────┬────────┴────────┬────────┘             ║
 ╚═══════════════════╪════════════════╪════════════════╪═══════════════════════╝
                     │                │                │
            ExecReport│       TradeEvent│      BookUpdate│
            (→ OEG)   │       (→ MDG)   │      (→ MDG)   │
                     │                │                │
 ╔═══════════════════╪════════════════╪════════════════╪═══════════════════════╗
 ║  KAFKA BUS (optional, Optiq KFK)  │                │                        ║
 ║  ┌─────────────────────────────────────────────────────────────────────┐     ║
 ║  │  KafkaBus (shared by all MECoreActors)                              │     ║
 ║  │                                                                     │     ║
 ║  │  • eunex.orders        ← raw Order on entry                        │     ║
 ║  │  • eunex.trades        ← Trade on each fill                        │     ║
 ║  │  • eunex.market-data   ← BBO snapshot on book update               │     ║
 ║  │  • eunex.recovery.fragments ← recovery data                        │     ║
 ║  │                                                                     │     ║
 ║  │  Enabled: EUNEX_USE_KAFKA=ON + EUNEX_KAFKA_BROKERS env var         │     ║
 ║  │  Disabled: no-op stub compiles in (default)                        │     ║
 ║  └─────────────────────────────────────────────────────────────────────┘     ║
 ╚═════════════════════════════════════════════════════════════════════════════╝
                     │                │                │
 ╔═══════════════════╪════════════════╪════════════════╪═══════════════════════╗
 ║  CORE 2 — Market Data             ▼                ▼                        ║
 ║  ┌─────────────────────────────────────────────────────────────────────┐     ║
 ║  │  MDGActor                                                           │     ║
 ║  │                                                                     │     ║
 ║  │  • BBO snapshots per symbol (bestBid, bestAsk, depths)             │     ║
 ║  │  • Recent trade history (last 200 trades)                          │     ║
 ║  │  • Trade count, volume, last price per symbol                      │     ║
 ║  │  • Thread-safe reads for Python dashboard bridge                   │     ║
 ║  └─────────────────────────────────────────────────────────────────────┘     ║
 ╚═════════════════════════════════════════════════════════════════════════════╝
                                               │
                                          TradeEvent
                                          (→ Clearing)
                                               │
 ╔═════════════════════════════════════════════╪═══════════════════════════════╗
 ║  CORE 3 — Post-Trade & AI                  ▼                                ║
 ║  ┌─────────────────────────────┐    ┌─────────────────────────────┐         ║
 ║  │  ClearingHouseActor         │    │  AITraderActor              │         ║
 ║  │                             │    │                             │         ║
 ║  │  • Session → Member map     │    │  • 10 members (MBR01-10)   │         ║
 ║  │  • Capital tracking         │    │  • 3 strategies:           │         ║
 ║  │  • Holdings per symbol      │    │    momentum, mean_revert,  │         ║
 ║  │  • P&L calculation          │    │    random                  │         ║
 ║  │  • Leaderboard (sorted)     │    │  • Periodic order bursts   │         ║
 ║  │  • Thread-safe for bridge   │    │  • BBO + price history     │         ║
 ║  └─────────────────────────────┘    └──────────────┬──────────────┘         ║
 ║                                                     │                       ║
 ║                                              NewOrderEvent                  ║
 ║                                              (→ OEG → ME)                   ║
 ╚═════════════════════════════════════════════════════════════════════════════╝

3. Optiq Naming Alignment

EuNEx components are named to match Euronext Optiq production terminology:

 Optiq Production                EuNEx Class             File
 ═══════════════════════         ════════════════════     ═══════════════════════════
 OEActor (OE Gateway)      ───► OEGActor                 src/actors/OEGActor.hpp
 LogicalCoreActor + Book   ───► MECoreActor              src/actors/MECoreActor.hpp
 Book (order book engine)  ───► Book                     src/common/Book.hpp
 MDLimitLogicalCoreHandler ───► MDGActor                 src/actors/MDGActor.hpp
 OEG FIX Gateway           ───► FIXAcceptorActor         src/actors/FIXAcceptorActor.hpp
 Clearing House (PTB path) ───► ClearingHouseActor       src/actors/ClearingHouseActor.hpp
 Member Trading Bots       ───► AITraderActor            src/actors/AITraderActor.hpp
 RecoveryProxy             ───► RecoveryProxy            src/recovery/RecoveryProxy.hpp
 IacaAggregatorActor       ───► IacaAggregator           src/iaca/IacaAggregator.hpp

Why these names?

OEG = Order Entry Gateway (the Optiq front-end for all order flow)
ME = Matching Engine (the core Book + LogicalCoreActor in Optiq)
MDG = Market Data Gateway (publishes BBO, trades, depth to consumers)
FIXAcceptor = Optiq's FIX protocol acceptor component within OEG

4. Actor Topology

Core Affinity Layout

 ┌──────────────────────────────────────────────────────────────────────────────┐
 │  PRESENTATION (Python)                                                       │
 │                                                                              │
 │  ┌─ nginx :7860 ────────────────────────────────────────────────────────┐   │
 │  │  /       → Dashboard :8090      /ch/ → Clearing House UI :8091      │   │
 │  └──────────┬──────────────────────────────┬────────────────────────────┘   │
 │             │                              │                                │
 │  ┌──────────▼─────────────────┐  ┌────────▼───────────────────────┐        │
 │  │  Dashboard (Flask :8090)   │  │  Clearing House UI (Flask :8091)│        │
 │  │  • Order Book, Charts      │  │  • Leaderboard, P&L, Holdings  │        │
 │  │  • OHLCV, SSE streaming   │  │  • Member portfolios           │        │
 │  │  • SQLite for history      │  │                                 │        │
 │  └──────────┬─────────────────┘  └────────┬───────────────────────┘        │
 │             │ getSnapshot()               │ getLeaderboard()               │
 │             │ getRecentTrades()           │ (thread-safe reads)            │
 │             │ (thread-safe reads)         │                                │
 └─────────────┼─────────────────────────────┼────────────────────────────────┘
               │                             │
               ▼                             ▼
 ┌──────────────────────────────────────────────────────────────────────────────┐
 │  C++ ACTOR ENGINE                                                            │
 │                                                                              │
 │  ┌─ CPU Core 0 ─────────────────┐    ┌─ CPU Core 1 ────────────────────┐   │
 │  │                               │    │                                 │   │
 │  │  OEGActor                     │    │  MECoreActor (AAPL, sym=1)     │   │
 │  │   • Symbol → Book routing     │    │  MECoreActor (MSFT, sym=2)     │   │
 │  │   • Exec report fanout        │    │  MECoreActor (GOOGL, sym=3)    │   │
 │  │                               │    │  MECoreActor (EURO50, sym=4)   │   │
 │  │  FIXAcceptorActor             │    │                                 │   │
 │  │   • TCP :9001                 │    │  Each owns a Book instance     │   │
 │  │   • FIX 4.4 protocol         │    │  KafkaBus* → Kafka topics      │   │
 │  │                               │    │  No locks in matching path     │   │
 │  └───────────────────────────────┘    └─────────────────────────────────┘   │
 │                                                                              │
 │  ┌─ CPU Core 2 ─────────────────┐    ┌─ CPU Core 3 ────────────────────┐   │
 │  │                               │    │                                 │   │
 │  │  MDGActor                     │    │  ClearingHouseActor            │   │
 │  │   • BBO per symbol            │    │   • 10 members, capital, P&L   │   │
 │  │   • Trade history             │    │   • Session → Member mapping   │   │
 │  │   • Snapshot queries          │    │                                 │   │
 │  │   ◄── Dashboard reads here   │    │  AITraderActor                  │   │
 │  │                               │    │   • 10 AI members              │   │
 │  │                               │    │   • Momentum / MeanRev / Rand  │   │
 │  └───────────────────────────────┘    └─────────────────────────────────┘   │
 │                                                                              │
 │  ┌─ KafkaBus (optional) ────────────────────────────────────────────────┐   │
 │  │  eunex.orders │ eunex.trades │ eunex.market-data │ eunex.recovery   │   │
 │  └──────────────────────────────────────────────────────────────────────┘   │
 │                                                                              │
 └──────────────────────────────────────────────────────────────────────────────┘

Event::Pipe Connections

 FIXAcceptorActor ──NewOrderEvent──────► OEGActor ──NewOrderEvent──► MECoreActor
                                                  ──CancelOrderEvent──►
                                                  ──ModifyOrderEvent──►

 MECoreActor ──ExecReportEvent──► OEGActor ──ExecReportEvent──► FIXAcceptorActor
                                           ──ExecReportEvent──► AITraderActor

 MECoreActor ──TradeEvent──────► MDGActor
             ──BookUpdateEvent─► MDGActor
             ──TradeEvent──────► ClearingHouseActor
             ──publishOrder()──► KafkaBus → eunex.orders      (if Kafka enabled)
             ──publishTrade()──► KafkaBus → eunex.trades       (if Kafka enabled)
             ──publishMarketData()► KafkaBus → eunex.market-data (if Kafka enabled)

 AITraderActor ──NewOrderEvent──► OEGActor (via pipe)

 Dashboard (Python) ──getSnapshot()──────► MDGActor          (thread-safe read)
                    ──getRecentTrades()──► MDGActor          (thread-safe read)
 Clearing House UI  ──getLeaderboard()───► ClearingHouseActor (thread-safe read)

5. Data Flow

Order Lifecycle (New Limit Order)

 ┌──────────┐    FIX 35=D     ┌──────────────────┐   NewOrderEvent    ┌──────────────┐
 │  Client  │ ──────────────► │ FIXAcceptorActor  │ ────────────────► │   OEGActor   │
 │ (FIX)    │                 │ parse FIX tags    │                   │ route by sym │
 └──────────┘                 │ map symbol string │                   └──────┬───────┘
                              │ to SymbolIndex_t  │                          │
                              └───────────────────┘                          │
                                                                    NewOrderEvent
                                                                    (Event::Pipe)
                                                                             │
                                                                             ▼
                              ┌────────────────────────────────────────────────────┐
                              │                  MECoreActor                        │
                              │                                                    │
                              │   1. KafkaBus.publishOrder() → eunex.orders *      │
                              │   2. RecoveryProxy.cause() — persist fragment      │
                              │   3. Book.newOrder() — price-time matching         │
                              │   4. For each fill:                                │
                              │      a. Trade generated (buyer + seller session)   │
                              │      b. TradeEvent → MDGActor                     │
                              │      c. TradeEvent → ClearingHouseActor           │
                              │      d. KafkaBus.publishTrade() → eunex.trades *  │
                              │   5. ExecReportEvent → OEGActor (ack/fill/reject) │
                              │   6. BookUpdateEvent → MDGActor (new BBO)         │
                              │   7. KafkaBus.publishMarketData() → eunex.md *    │
                              │   8. IACA fragments → IacaAggregator              │
                              │                                                    │
                              │   * only when EUNEX_KAFKA_BROKERS is set           │
                              └────────────────────────────────────────────────────┘
                                         │                          │
                                ExecReportEvent              TradeEvent
                                         │                          │
                                         ▼                          ▼
                              ┌───────────────────┐    ┌──────────────────────┐
                              │    OEGActor        │    │  ClearingHouseActor  │
                              │ fanout to:         │    │  • map session→member│
                              │  • FIXAcceptor     │    │  • update capital    │
                              │  • AITrader        │    │  • update holdings   │
                              └────────┬──────────┘    └──────────────────────┘
                                       │
                              FIX 35=8 (ExecReport)
                                       │
                                       ▼
                              ┌───────────────────┐
                              │     Client         │
                              │  receives fill     │
                              └───────────────────┘

Market Data Flow

 MECoreActor ──TradeEvent──────────────► MDGActor
             ──BookUpdateEvent──────────►    │
             ──publishTrade()────────────► KafkaBus → eunex.trades *
             ──publishMarketData()───────► KafkaBus → eunex.market-data *
                                              │
                                              ▼
                                     ┌──────────────────────┐
                                     │  MarketDataSnapshot   │
                                     │  per SymbolIndex_t:   │
                                     │                       │
                                     │  • bestBid, bestAsk  │
                                     │  • lastTradePrice    │
                                     │  • lastTradeQty      │
                                     │  • totalBidQty       │
                                     │  • totalAskQty       │
                                     │  • tradeCount        │
                                     │  • updateTime (ns)   │
                                     │                       │
                                     │  recentTrades[]      │
                                     │  (last 200 trades)   │
                                     └──────────────────────┘
                                              │
                                     getSnapshot() / getRecentTrades()
                                     (thread-safe, mutex-protected)
                                              │
                              ┌───────────────┴───────────────┐
                              │                               │
                              ▼                               ▼
                    ┌───────────────────┐         ┌───────────────────────┐
                    │  Dashboard :8090  │         │  Clearing House :8091 │
                    │  (Flask + SSE)    │         │  (Flask)              │
                    │                   │         │                       │
                    │  Order Book view  │         │  getLeaderboard()    │
                    │  Trade charts     │         │  Member P&L, holdings│
                    │  OHLCV history    │         │                       │
                    └───────────────────┘         └───────────────────────┘
                              │                               │
                              └───────────┬───────────────────┘
                                          │
                                     nginx :7860
                                     (reverse proxy)
                                          │
                                          ▼
                                      Browser

 * KafkaBus publishes only when EUNEX_KAFKA_BROKERS is set at runtime

6. Core Components

6.1 SimplxShim — Actor Framework (`src/engine/SimplxShim.hpp`)

The actor engine emulates the Tredzone Simplx framework API:

Simplx Concept	EuNEx Implementation
`Actor`	Base class with event handlers, mailbox
`Event::Pipe`	Lock-free cross-actor channel
`ActorId`	`{id: uint64, coreId: uint8}`
`Engine`	Multi-threaded scheduler with core affinity
`Callback`	Timer-like periodic invocation
`AsyncService`	Service locator pattern

Two operating modes:

Synchronous (tests): events delivered inline, single thread
Threaded (Engine::runFor): per-core OS threads, mailbox queues

 Synchronous Mode (unit tests)          Threaded Mode (Engine::runFor)
 ═══════════════════════════            ═══════════════════════════════

 ActorA.pipe.push<Event>()              ActorA.pipe.push<Event>()
       │                                       │
       ▼                                       ▼
 ActorB.onEvent() ← inline              Mailbox[coreB].enqueue(λ)
                                               │
                                        Core B thread:
                                         mbox.waitAndDrain()
                                               │
                                               ▼
                                        ActorB.onEvent()

6.2 Types (`src/common/Types.hpp`)

Price_t       = int64_t     // Fixed-point, PRICE_SCALE = 100'000'000
Quantity_t    = uint64_t
OrderId_t     = uint64_t    // Exchange-assigned order ID
ClOrdId_t     = uint64_t    // Client order ID
SymbolIndex_t = uint32_t    // Instrument identifier
TradeId_t     = uint64_t
SessionId_t   = uint16_t    // Client session identifier
MemberId_t    = uint16_t    // Clearing member identifier
Timestamp_ns  = uint64_t    // Nanosecond timestamp

Price conversion:

Price_t px = toFixedPrice(150.25);  // → 15'025'000'000
double  d  = toDouble(px);          // → 150.25

6.3 Order & Trade Structs

 Order (88 bytes, packed)                Trade (72 bytes, packed)
 ═══════════════════════                 ═══════════════════════
 orderId      : uint64                   tradeId       : uint64
 clOrdId      : uint64                   symbolIdx     : uint32
 symbolIdx    : uint32                   price         : int64
 side         : uint8  (Buy=1,Sell=2)    quantity      : uint64
 ordType      : uint8  (Market=1,Lim=2)  buyOrderId    : uint64
 tif          : uint8  (Day/GTC/IOC/FOK) sellOrderId   : uint64
 price        : int64                    buyClOrdId    : uint64
 quantity     : uint64                   sellClOrdId   : uint64
 remainingQty : uint64                   matchTime     : uint64
 entryTime    : uint64                   buySessionId  : uint16
 sessionId    : uint16                   sellSessionId : uint16
 status       : uint8

7. Event System

Events flow between actors via Event::Pipe. Each event struct inherits tredzone::Actor::Event:

 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                           EVENT CATALOG                                     │
 │                                                                             │
 │  NewOrderEvent         OEG → ME       New order submission                 │
 │  CancelOrderEvent      OEG → ME       Cancel resting order                │
 │  ModifyOrderEvent      OEG → ME       Modify price/qty (cancel-replace)   │
 │  ExecReportEvent       ME → OEG       Ack, fill, partial, reject          │
 │  TradeEvent            ME → MDG/CH    Trade execution                      │
 │  BookUpdateEvent       ME → MDG/AI    BBO + depth snapshot                │
 │  RecoveryFragmentEvent ME → Persist   Recovery persistence                │
 │                                                                             │
 │  Direction Key:                                                             │
 │  OEG = OEGActor       ME = MECoreActor     MDG = MDGActor                │
 │  CH = ClearingHouse    AI = AITraderActor                                  │
 └─────────────────────────────────────────────────────────────────────────────┘

Event::Pipe Usage Pattern

// In MECoreActor constructor:
oePipe_ = Event::Pipe(*this, oeGatewayId);   // pipe to OEG
mdPipe_ = Event::Pipe(*this, marketDataId);   // pipe to MDG

// Pushing an event (lock-free, zero-copy in same-core mode):
oePipe_.push<ExecReportEvent>(report, sessionId);
mdPipe_.push<TradeEvent>(trade);

8. Order Book & Matching

Book (`src/common/Book.hpp`)

The Book class implements price-time priority matching:

 BIDS (sorted descending)              ASKS (sorted ascending)
 ════════════════════════              ════════════════════════

 Price    │ Orders (FIFO)              Price    │ Orders (FIFO)
 ─────────┼──────────────              ─────────┼──────────────
 155.00   │ [100] [50]                 157.00   │ [200]
 154.50   │ [200]                      158.00   │ [100] [150]
 154.00   │ [75] [100] [25]            159.00   │ [300]
 153.00   │ [500]                      160.00   │ [50]

 std::map<Price_t,                     std::map<Price_t,
   vector<Order>,                        vector<Order>,
   std::greater<>>                       std::less<>>

Matching algorithm:

 Incoming BUY @ 158.00, qty=250
 ──────────────────────────────

 Step 1: Match vs best ask 157.00 (qty=200)
         → Trade: 200 @ 157.00
         → Ask level 157.00 exhausted

 Step 2: Match vs next ask 158.00 (qty=100 + 150)
         → Trade: 50 @ 158.00 (from first order, partial)
         → Remaining incoming qty = 0 → DONE

 Step 3: Incoming fully filled
         → ExecReport: status=Filled, filledQty=250

Order types:

Limit: rests on book if no match; price-time priority
Market: sweeps all levels; never rests (IOC behavior)

Time-in-force:

Day: rests until end of session
IOC: fill what's available, cancel remainder
FOK: fill all or reject entirely

MECoreActor (`src/actors/MECoreActor.hpp`)

 NewOrderEvent ──► MECoreActor.onEvent()
                        │
                        ├── RecoveryProxy.cause(persistenceId, order, λ)
                        │     └── Fragment persisted to store
                        │
                        ├── book_.newOrder(order, onTrade, onExec)
                        │     ├── matchBuy() / matchSell()
                        │     │     └── for each fill: onTrade(trade)
                        │     └── onExec(report)
                        │
                        ├── oePipe_.push<ExecReportEvent>(report, session)
                        ├── mdPipe_.push<TradeEvent>(trade)         [per fill]
                        ├── mdPipe_.push<BookUpdateEvent>(snapshot)  [if book changed]
                        └── chPipe_.push<TradeEvent>(trade)         [per fill, if CH wired]

9. Recovery & IACA

RecoveryProxy (`src/recovery/RecoveryProxy.hpp`)

 ┌──────────────────────────────────────────────────────────────────────┐
 │  RecoveryProxy (per MECoreActor)                                     │
 │                                                                      │
 │  cause(persistenceId, payload, callback)                             │
 │    → persist Fragment to FragmentStore                               │
 │    → callback returns nextCount (# children expected)               │
 │    → always executes (Master AND Mirror)                            │
 │                                                                      │
 │  effect(fn, args...)                                                 │
 │    → executes fn only on MASTER                                     │
 │    → side effects: send ExecReports, publish trades                 │
 │                                                                      │
 │  recoveryEffect(fn, args...)                                         │
 │    → executes fn only on MIRROR (during failover replay)            │
 │                                                                      │
 │  ┌────────────────┐            ┌────────────────┐                   │
 │  │  MASTER         │            │  MIRROR         │                   │
 │  │  cause()  ✓     │  ◄──────►  │  cause()  ✓     │                   │
 │  │  effect() ✓     │  Fragment   │  effect() ✗     │                   │
 │  │  recEff() ✗     │  Store      │  recEff() ✓     │                   │
 │  └────────────────┘  (shared)   └────────────────┘                   │
 └──────────────────────────────────────────────────────────────────────┘

IACA Fragment Chains (`src/iaca/IacaAggregator.hpp`)

 Chain Completion Algorithm:
 ══════════════════════════

 Fragment 1 (ROOT: NEW_ORDER_BUY)       nextCount = 2
     ├── Fragment 2 (ACK_DATA)          nextCount = 0
     └── Fragment 3 (TRADE_DATA)        nextCount = 0

 Completion check:
   sum(nextCount) = 2 + 0 + 0 = 2
   total fragments = 3
   complete when: sum == total - 1     →  2 == 3 - 1  ✓

 On completion:
   → NewOrderHandler fires
   → Generates IA SBE message (future: IDS/PTB/SATURN)

10. Kafka Bus

Overview

The Kafka Bus (src/persistence/KafkaBus.hpp) mirrors the Optiq KFK (Kafka Bus) that connects the Matching Engine to downstream consumers: MDG, PTB, Clearing, IDS, and SATURN.

When EUNEX_USE_KAFKA is enabled at compile time and EUNEX_KAFKA_BROKERS is set at runtime, the bus publishes events to Kafka topics in real time. When disabled, a no-op stub compiles in its place so the engine runs standalone.

Topics

  Topic                        Content                  Key
  ─────────────────────────────────────────────────────────────
  eunex.orders                 Raw Order structs        symbolIdx
  eunex.trades                 Trade structs            symbolIdx
  eunex.market-data            BBO snapshots            symbolIdx
  eunex.recovery.fragments     Recovery fragments       originId:originKey
  eunex.control                Control messages         (reserved)

Architecture

  MECoreActor (per symbol)
       │
       ├─ onEvent(NewOrderEvent)
       │     ├─ kafka_->publishOrder(order)         → eunex.orders
       │     ├─ onTrade callback:
       │     │     ├─ kafka_->publishTrade(trade)    → eunex.trades
       │     │     └─ mdPipe_ / chPipe_ (actors)
       │     └─ publishBookUpdate()
       │           └─ kafka_->publishMarketData(...) → eunex.market-data
       │
       └─ KafkaBus* kafka_  (nullptr when disabled)

Compile-Time Toggle

cmake .. -DEUNEX_USE_KAFKA=ON    # requires librdkafka-dev
cmake .. -DEUNEX_USE_KAFKA=OFF   # no-op stub (default)

Runtime Configuration

Set EUNEX_KAFKA_BROKERS environment variable:

export EUNEX_KAFKA_BROKERS=kafka:9092
./eunex_me

The engine prints Kafka connection status at startup and publishes cumulative stats (orders, trades, market-data messages) every 10 rounds.

Docker Deployment

docker/docker-compose.yml runs Kafka in KRaft mode (no ZooKeeper) using apache/kafka:3.9.0, creates all topics via kafka-init, then starts the engine with EUNEX_KAFKA_BROKERS=kafka:9092.

cd docker
docker compose up --build

11. FIX Protocol Gateway

FIXAcceptorActor (`src/actors/FIXAcceptorActor.hpp`)

 ┌──────────────────────────────────────────────────────────────────────────┐
 │  FIXAcceptorActor (TCP :9001)                                            │
 │                                                                          │
 │  ┌─ Accept Thread ──────────────────────────────────────────────────┐    │
 │  │  while(running):                                                  │    │
 │  │    sock = accept(listenSock)                                      │    │
 │  │    create FIXSession { sock, sessionId, senderCompId }           │    │
 │  │    spawn client recv thread                                       │    │
 │  └───────────────────────────────────────────────────────────────────┘    │
 │                                                                          │
 │  ┌─ Client Recv Thread (per session) ───────────────────────────────┐    │
 │  │  while(loggedOn):                                                 │    │
 │  │    data = recv(sock)                                              │    │
 │  │    msgs = parseFIXMessages(data)                                  │    │
 │  │    for msg in msgs:                                               │    │
 │  │      switch(msg[35]):                                             │    │
 │  │        "A" → handleLogon()                                        │    │
 │  │        "D" → handleNewOrderSingle() → push NewOrderEvent → OEG  │    │
 │  │        "F" → handleCancelRequest()  → push CancelOrderEvent     │    │
 │  │        "G" → handleCancelReplace()  → push ModifyOrderEvent     │    │
 │  │        "5" → logout                                               │    │
 │  └───────────────────────────────────────────────────────────────────┘    │
 │                                                                          │
 │  ┌─ Actor Thread (onEvent) ─────────────────────────────────────────┐    │
 │  │  onEvent(ExecReportEvent):                                        │    │
 │  │    find session by sessionId                                      │    │
 │  │    build FIX ExecutionReport (35=8)                               │    │
 │  │    send() over TCP to client                                      │    │
 │  └───────────────────────────────────────────────────────────────────┘    │
 └──────────────────────────────────────────────────────────────────────────┘

Supported FIX messages:

Tag 35	Message	Direction
A	Logon	Inbound
5	Logout	Inbound
0	Heartbeat	Inbound
D	NewOrderSingle	Inbound
F	OrderCancelRequest	Inbound
G	OrderCancelReplaceRequest	Inbound
8	ExecutionReport	Outbound

Symbol mapping:

Symbol String	SymbolIndex_t
AAPL	1
MSFT	2
GOOGL	3
TSLA	4
NVDA	5
AMD	6
ENX	7

12. Clearing House

ClearingHouseActor (`src/actors/ClearingHouseActor.hpp`)

 ┌──────────────────────────────────────────────────────────────────────────┐
 │  ClearingHouseActor                                                      │
 │                                                                          │
 │  Session-to-Member Mapping:                                             │
 │  ┌──────────────────────────────────────────────────────────────────┐    │
 │  │  SessionId 100-109 ──► MemberId 1-10  (FIX gateway clients)    │    │
 │  │  SessionId 200-209 ──► MemberId 1-10  (AI traders)             │    │
 │  └──────────────────────────────────────────────────────────────────┘    │
 │                                                                          │
 │  On TradeEvent:                                                         │
 │  ┌──────────────────────────────────────────────────────────────────┐    │
 │  │  1. Resolve buySessionId → buyMember                             │    │
 │  │  2. Resolve sellSessionId → sellMember                           │    │
 │  │  3. Buy side:                                                    │    │
 │  │     capital -= price × quantity                                  │    │
 │  │     holdings[symbol].quantity += quantity                        │    │
 │  │     holdings[symbol].avgCost updated (weighted average)         │    │
 │  │  4. Sell side:                                                   │    │
 │  │     capital += price × quantity                                  │    │
 │  │     holdings[symbol].quantity -= quantity                        │    │
 │  │  5. Both sides: tradeCount++                                    │    │
 │  └──────────────────────────────────────────────────────────────────┘    │
 │                                                                          │
 │  Members (10):                                                          │
 │  ┌────────┬──────────┬─────────────────┬────────┐                       │
 │  │ Name   │ Capital  │ Holdings        │ Trades │                       │
 │  ├────────┼──────────┼─────────────────┼────────┤                       │
 │  │ MBR01  │ 100000.0 │ {sym→qty,cost}  │ 0      │                       │
 │  │ MBR02  │ 100000.0 │ {sym→qty,cost}  │ 0      │                       │
 │  │ ...    │ ...      │ ...             │ ...    │                       │
 │  │ MBR10  │ 100000.0 │ {sym→qty,cost}  │ 0      │                       │
 │  └────────┴──────────┴─────────────────┴────────┘                       │
 │                                                                          │
 │  getLeaderboard():                                                      │
 │    sorted by capital descending                                         │
 │    returns: memberId, name, capital, pnl, tradeCount, holdingCount     │
 │    thread-safe (mutex) for Python bridge reads                          │
 └──────────────────────────────────────────────────────────────────────────┘

13. AI Trading Members

AITraderActor (`src/actors/AITraderActor.hpp`)

 ┌──────────────────────────────────────────────────────────────────────────┐
 │  AITraderActor — 10 automated trading members                            │
 │                                                                          │
 │  Members:                                                               │
 │  ┌────────┬───────────┬────────────────┬──────────────┐                  │
 │  │ Name   │ SessionId │ Strategy       │ Description  │                  │
 │  ├────────┼───────────┼────────────────┼──────────────┤                  │
 │  │ MBR01  │ 200       │ Momentum       │ Follow trend │                  │
 │  │ MBR02  │ 201       │ MeanReversion  │ Fade moves   │                  │
 │  │ MBR03  │ 202       │ Random         │ Noise trader │                  │
 │  │ MBR04  │ 203       │ Momentum       │              │                  │
 │  │ ...    │ ...       │ (rotates)      │              │                  │
 │  │ MBR10  │ 209       │ Random         │              │                  │
 │  └────────┴───────────┴────────────────┴──────────────┘                  │
 │                                                                          │
 │  Strategy Details:                                                      │
 │  ┌──────────────────────────────────────────────────────────────────┐    │
 │  │                                                                  │    │
 │  │  MOMENTUM:                                                       │    │
 │  │    if last N prices trending up → BUY (follow the trend)        │    │
 │  │    if last N prices trending down → SELL                        │    │
 │  │    price = BBO ± small offset                                   │    │
 │  │                                                                  │    │
 │  │  MEAN REVERSION:                                                 │    │
 │  │    if price > moving average → SELL (expect revert)             │    │
 │  │    if price < moving average → BUY                              │    │
 │  │    price = BBO ± small offset                                   │    │
 │  │                                                                  │    │
 │  │  RANDOM:                                                         │    │
 │  │    random side (50/50), random qty (10-100)                     │    │
 │  │    price around midpoint with random spread                     │    │
 │  │                                                                  │    │
 │  │  LLM (Python CH only):                                          │    │
 │  │    sends portfolio + market data to LLM                         │    │
 │  │    expects JSON response: symbol, side, quantity, price, reason │    │
 │  │    uses same provider chain as AI Analyst                       │    │
 │  │    falls back to random on LLM failure                          │    │
 │  │    explanations shown in CH dashboard panel                     │    │
 │  │                                                                  │    │
 │  └──────────────────────────────────────────────────────────────────┘    │
 │                                                                          │
 │  Data Sources:                                                          │
 │    • BookUpdateEvent → BBO (bestBid, bestAsk) per symbol               │
 │    • TradeEvent → price history (last 50 prices) per symbol            │
 │    • ExecReportEvent → order fill confirmations                        │
 │                                                                          │
 │  Output:                                                                │
 │    • NewOrderEvent → OEGActor (via Event::Pipe)                        │
 │    • ~30s intervals via Actor::Callback                                │
 └──────────────────────────────────────────────────────────────────────────┘

14. Market Simulation

Both the C++ engine and the Python dashboard include market simulation to continuously generate orders and trades.

C++ Engine (AITraderActor)

The AITraderActor generates orders every ~3 seconds per round. Each of the 10 AI members picks a random symbol and applies its strategy (Momentum, Mean Reversion, or Random). All strategies use per-symbol reference prices matching real market levels:

Symbol	Reference Price
AAPL	$154.00
MSFT	$324.00
GOOGL	$141.00
TSLA	$375.00
NVDA	$201.00
AMD	$320.00
ENX	€146.00

When no BBO data is available yet, the fallback submitOrder() generates prices within ±3 ticks of the reference price instead of random values.

Python Dashboard (MarketSimulator)

The dashboard runs a MarketSimulator thread that generates orders when the session status is "active":

 Configuration (shared/config.py):
   SIM_INTERVAL           = 30s    (env: EUNEX_SIM_INTERVAL)
   SIM_ORDERS_PER_ROUND   = 4      (env: EUNEX_SIM_ORDERS)

 Per round (every SIM_INTERVAL seconds):
   For each of 7 symbols:
     1. Submit SIM_ORDERS_PER_ROUND limit orders near current mid price (±0.5%)
     2. Submit 1 crossing order that will match against the book
     → Generates resting orders + at least 1 trade per symbol per round

Order flow:

Session "Start Day" → seeds initial orders (2 bid + 2 ask per symbol)
Simulation thread wakes every 30s → submits ~35 orders → ~7 trades
All trades are persisted to SQLite (trades table + OHLCV aggregation)
Dashboard chart shows candlestick data from OHLCV buckets

Seed Orders (Session Start)

When the dashboard session starts, 4 orders are seeded per symbol to establish a market:

 For each symbol at startPrice:
   Buy  @ startPrice - 1.00, qty=100
   Buy  @ startPrice - 0.50, qty=150
   Sell @ startPrice + 0.50, qty=200
   Sell @ startPrice + 1.00, qty=100

Daily Close Persistence

When the session ends ("End Day"), closing prices are saved to the daily_close SQLite table:

 daily_close table:
   symbol TEXT, trade_date TEXT, close_price REAL, bid REAL, ask REAL,
   volume INTEGER, trade_count INTEGER
   PRIMARY KEY (symbol, trade_date)

On the next "Start Day", the engine loads the most recent closing prices from daily_close and uses them as seed prices instead of the hardcoded startPrice from config. This ensures price continuity across trading sessions.

Flow:

Session "End Day" → _save_closing_prices() writes current snapshot to daily_close
Next "Start Day" → _seed_initial_orders() calls get_last_closing_prices() from DB
If closing prices exist → seed around those prices
If no history → fall back to startPrice from shared/config.py

The simulator also loads closing prices on startup via _load_closing_refs().

Ticker Tape

The dashboard displays a scrolling ticker tape below the header showing all 7 symbols with:

Current price, percentage change (vs. previous price), volume
Green/red arrows for up/down movement
Auto-updates via SSE snapshot events

OHLCV Candlestick Chart

The price chart renders OHLCV data as candlestick bars using a custom Chart.js plugin:

Green candles (close >= open), red candles (close < open)
High/low wicks drawn as vertical lines
Volume bars on secondary axis with matching colors
Tooltip shows full OHLCV values per bar

15. AI Market Analyst

The dashboard includes an AI analyst powered by local or cloud LLM providers.

Provider Fallback Chain

 Auto mode tries in order:
   1. Ollama (local)    → POST {OLLAMA_HOST}/api/chat
   2. Groq (cloud)      → POST api.groq.com/openai/v1/chat/completions
   3. HuggingFace       → POST router.huggingface.co/v1/chat/completions

Environment Variables

Variable	Default	Description
OLLAMA_HOST	http://localhost:11434	Ollama API endpoint
OLLAMA_MODEL	llama3.2:3b	Default Ollama model
GROQ_API_KEY	(empty)	Groq API key
GROQ_MODEL	llama-3.1-8b-instant	Default Groq model
HF_TOKEN	(empty)	HuggingFace token
HF_MODEL	Qwen/Qwen2.5-7B-Instruct	Default HF model

Prompt Template

The analyst builds a market context prompt from current trades and order book:

 You are a concise financial market analyst for the EuNEx simulated exchange.
 Time: HH:MM:SS | Session: ACTIVE

 Recent trades:
   AAPL: 12 trade(s), range 153.50-154.50, vol 1200, last 154.10
   MSFT: 8 trade(s), range 323.80-324.20, vol 800, last 324.00
   ...

 Order book:
   AAPL: Bid 153.80 / Ask 154.20 (spread 0.40)
   ...

 In 3-4 sentences: activity level, notable moves, market sentiment.

API Endpoints

Endpoint	Method	Description
/ai/generate	POST	Trigger async LLM generation
/ai/insights	GET	Get cached insight history
/ai/config	GET	Provider availability/status
/ai/select	POST	Switch provider/model

Insights are broadcast via SSE ai_insight event and cached in memory (last 20).

16. Developer Message Flow Visualizer

The dashboard includes a "Message Flow" tab that traces the full order lifecycle through all system components. This is a developer tool for understanding and debugging the Optiq-modeled pipeline.

Pipeline Stages

 ┌─────┐    ┌──────┐    ┌───────┐    ┌───────┐    ┌────┐    ┌────┐
 │ OEG │ ─► │ Book │ ─► │ Match │ ─► │ Trade │ ─► │ DB │ ─► │ CH │
 └─────┘    └──────┘    └───────┘    └───────┘    └────┘    └────┘
   Order      Insert      Fill         Record      SQLite    Clear
   Entry      /Status     Partial      Trade       Persist   House

Each stage logs a timestamped message with detail text. Messages flow via SSE msgflow events for real-time display.

Implementation

The visualizer uses Python function patching to intercept the matching engine methods:

engine.submit_order() → logs OEG (entry) + Book (status) + Match (fill)
engine.cancel_order() → logs OEG (cancel) + Book (cancelled)
broadcast_event("trade", ...) → logs Trade + DB + CH steps

API

Endpoint	Method	Description
/dev/messages	GET	Get recent message log (500 max)

UI Features

Pipeline counter: shows cumulative message count per stage
Live log: new messages appear at top with highlight animation
Clear: resets all counters and log entries

17. Engine Mode Switch

The dashboard supports two matching engine backends, switchable at runtime via a toggle in the header.

Architecture

 ┌──────────────────────────────────────────────────────────────────────────┐
 │  Dashboard (Flask :8090)                                                 │
 │                                                                          │
 │  ┌─────────────────────────────┐    ┌─────────────────────────────┐     │
 │  │  Python MatchingEngine       │    │  CppEngineBridge             │     │
 │  │  (built-in, default)         │    │  (FIX 4.4 TCP client)        │     │
 │  │                              │    │                              │     │
 │  │  • In-process order book     │    │  • Connects to :9001         │     │
 │  │  • Price-time priority       │    │  • Sends NewOrderSingle(D)   │     │
 │  │  • No compilation needed     │    │  • Sends CancelRequest (F)   │     │
 │  │  • SQLite persistence        │    │  • Sends CancelReplace (G)   │     │
 │  │  • Good for demos            │    │  • Receives ExecReport (8)   │     │
 │  └──────────────────────────────┘    │  • Logon/Logout/Heartbeat    │     │
 │                                      └──────────────┬───────────────┘     │
 │        _active_engine()                             │                     │
 │        returns engine or cpp_bridge                 │                     │
 │        based on engine_mode variable                │                     │
 └─────────────────────────────────────────────────────┼─────────────────────┘
                                                       │
                                              FIX 4.4 TCP :9001
                                                       │
                                                       ▼
                                       ┌───────────────────────────┐
                                       │  eunex_me (C++ engine)    │
                                       │  FIXAcceptorActor :9001   │
                                       │  OEG → MECore → MDG → CH │
                                       └───────────────────────────┘

Switching Modes

From the UI: The header contains a toggle switch [Python ○──── C++] with a status dot:

Green dot: C++ engine is running and reachable on port 9001
Red dot: C++ engine not detected
Health check runs every 15 seconds

From the API:

# Check current mode and C++ availability
GET /engine/mode
→ {"mode": "python", "cpp_available": true, "cpp_host": "localhost", "cpp_port": 9001}

# Switch to C++ engine
POST /engine/mode  {"mode": "cpp"}
→ {"mode": "cpp"}

# Switch back to Python
POST /engine/mode  {"mode": "python"}
→ {"mode": "python"}

Order Routing

When engine_mode == "cpp":

Dashboard builds a FIX NewOrderSingle (35=D) message
Sends it over TCP to eunex_me:9001
C++ engine matches and returns ExecutionReport (35=8)
Bridge parses the response and updates dashboard state (orders, trades, snapshots)
SSE events broadcast to browser as usual

When engine_mode == "python":

Orders processed by the built-in MatchingEngine class (default behavior)

Simulation orders (source=sim, source=seed) always use the Python engine regardless of mode.

FIX Message Flow (C++ Mode)

 Browser                Dashboard                C++ Engine
 ───────                ─────────                ──────────
   │  POST /order/new      │                          │
   │ ─────────────────►    │                          │
   │                       │  35=D NewOrderSingle     │
   │                       │ ────────────────────►    │
   │                       │                     Book::newOrder()
   │                       │                     match → Trade
   │                       │  35=8 ExecutionReport    │
   │                       │ ◄────────────────────    │
   │                       │  update state, SSE       │
   │  SSE: order, trade    │                          │
   │ ◄─────────────────    │                          │

Connection Lifecycle

 Toggle ON (→ C++)                Toggle OFF (→ Python)
 ═══════════════════              ════════════════════════
 1. TCP connect(:9001)            1. Send FIX Logout (35=5)
 2. Send FIX Logon (35=A)        2. Close TCP socket
 3. Start recv thread             3. Set mode = "python"
 4. Set mode = "cpp"              4. Orders route to MatchingEngine
 5. Orders route to bridge

18. Project Structure

 EuNEx/
 ├── CMakeLists.txt                    Build configuration
 ├── README.md                         Project overview
 │
 ├── src/
 │   ├── main.cpp                      Engine entry point, actor wiring
 │   │
 │   ├── common/
 │   │   ├── Types.hpp                 Core types (Price_t, Order, Trade, etc.)
 │   │   ├── Book.hpp                  Order book interface
 │   │   └── Book.cpp                  Price-time priority matching engine
 │   │
 │   ├── engine/
 │   │   └── SimplxShim.hpp            Actor framework (Simplx API compatible)
 │   │
 │   ├── actors/
 │   │   ├── Events.hpp                All inter-actor event definitions
 │   │   ├── OEGActor.hpp/cpp          Order Entry Gateway
 │   │   ├── MECoreActor.hpp/cpp       Matching Engine core (per symbol)
 │   │   ├── MDGActor.hpp/cpp          Market Data Gateway
 │   │   ├── FIXAcceptorActor.hpp/cpp  FIX 4.4 TCP protocol gateway
 │   │   ├── ClearingHouseActor.hpp/cpp Trade clearing & member positions
 │   │   └── AITraderActor.hpp/cpp     Automated trading members
 │   │
 │   ├── net/
 │   │   └── SocketCompat.hpp          Cross-platform socket abstraction
 │   │
 │   ├── recovery/
 │   │   ├── RecoveryProxy.hpp/cpp     Master/Mirror recovery gating
 │   │   └── (FragmentStore)           In-memory persistence (→ Kafka future)
 │   │
 │   ├── iaca/
 │   │   ├── Fragment.hpp              IACA fragment definitions
 │   │   ├── IacaAggregator.hpp/cpp    Fragment chain assembly & completion
 │   │   └── (handlers)                IA message generators
 │   │
 │   └── persistence/
 │       ├── PersistenceStore.hpp       Store interface
 │       └── KafkaStore.hpp             Kafka adapter (optional, librdkafka)
 │
 ├── dashboard/
 │   ├── app.py                          Flask dashboard + dual engine bridge
 │   ├── database.py                     SQLite (orders, trades, OHLCV)
 │   └── templates/index.html            Trading UI with engine toggle
 │
 ├── clearing_house/
 │   ├── app.py                          Flask CH portal + API
 │   ├── ch_database.py                  SQLite (members, holdings)
 │   ├── ch_ai_trader.py                 AI trading (momentum/mean_revert/random/llm)
 │   └── templates/                      CH web UI (leaderboard, portfolios)
 │
 ├── fix_gateway/
 │   └── fix_server.py                   Python FIX 4.4 TCP acceptor
 │
 ├── shared/
 │   └── config.py                       Centralized config (auto-loads .env)
 │
 ├── .env                                LLM and service configuration
 │
 ├── tests/
 │   ├── test_orderbook.cpp            Book unit tests (26 cases)
 │   ├── test_matching_engine.cpp      ME integration tests
 │   ├── test_threaded_engine.cpp      Multi-threaded actor tests
 │   ├── test_clearing_house.cpp       Clearing house tests (7 cases)
 │   ├── test_fix_gateway.cpp          FIX gateway tests (5 cases)
 │   └── test_ai_trader.cpp            AI trader tests (6 cases)
 │
 ├── examples/
 │   ├── ping_pong.cpp                 Basic actor communication demo
 │   └── simple_match.cpp              Simple order matching demo
 │
 └── docs/
     ├── developers-guide.md           This document
     └── process-diagram.md            Detailed Optiq architecture diagrams

19. Build & Test

Prerequisites

C++20 compiler: MSVC 19.30+, GCC 12+, Clang 15+
CMake: 3.16+
Optional: librdkafka (for Kafka persistence)

Build Commands

# Configure (default: tests ON, Kafka OFF)
cmake -B build -DEUNEX_BUILD_TESTS=ON

# Build
cmake --build build --config Release

# Run tests
cd build && ctest -C Release --output-on-failure

# Run engine
./build/Release/eunex_me

CMake Options

Option	Default	Description
`EUNEX_USE_SIMPLX`	OFF	Use real Simplx framework
`EUNEX_USE_KAFKA`	OFF	Enable Kafka persistence
`EUNEX_BUILD_TESTS`	ON	Build test binaries
`EUNEX_BUILD_EXAMPLES`	ON	Build example binaries

Test Suites

 ┌───────────────────────────────────────────────────────────────┐
 │  Test Suite              │ Cases │ What it verifies            │
 ├──────────────────────────┼───────┼─────────────────────────────┤
 │  OrderBookTest           │  26   │ Book matching, all TIFs,    │
 │                          │       │ multi-level sweeps, cancels │
 ├──────────────────────────┼───────┼─────────────────────────────┤
 │  MatchingEngineTest      │   -   │ MECoreActor event handling  │
 ├──────────────────────────┼───────┼─────────────────────────────┤
 │  ThreadedEngineTest      │   -   │ Multi-core Engine, mailbox  │
 ├──────────────────────────┼───────┼─────────────────────────────┤
 │  ClearingHouseTest       │   7   │ Capital, holdings, P&L,     │
 │                          │       │ session mapping, leaderboard│
 ├──────────────────────────┼───────┼─────────────────────────────┤
 │  FIXGatewayTest          │   5   │ Symbol mapping, actor       │
 │                          │       │ lifecycle, OEG routing      │
 ├──────────────────────────┼───────┼─────────────────────────────┤
 │  AITraderTest            │   6   │ Strategy execution, multi-  │
 │                          │       │ symbol, clearing integration│
 └───────────────────────────────────────────────────────────────┘

20. Configuration

Runtime Configuration (main.cpp)

Parameter	Value	Description
FIX port	9001	FIXAcceptorActor TCP listen port
Symbols	7	AAPL, MSFT, GOOGL, TSLA, NVDA, AMD, ENX
AI members	10	MBR01-MBR10
Initial capital	100,000.0	Per clearing member
AI trade interval	~3s	Per round in main loop
Price scale	10^8	Fixed-point decimal places

Seed Orders

The engine pre-populates order books with spread-defining orders:

 AAPL:   Sell 155.00/100, 154.50/200  |  Buy 153.50/150, 153.00/100
 MSFT:   Sell 325.00/100, 324.50/150  |  Buy 323.50/200, 323.00/100
 GOOGL:  Sell 142.00/100, 141.50/200  |  Buy 140.50/150, 140.00/100
 TSLA:   Sell 376.00/80,  375.50/120  |  Buy 374.50/100, 374.00/80
 NVDA:   Sell 202.00/100, 201.50/150  |  Buy 200.50/120, 200.00/100
 AMD:    Sell 321.00/90,  320.50/130  |  Buy 319.50/110, 319.00/80
 ENX:    Sell 147.00/60,  146.50/100  |  Buy 145.50/80,  145.00/60

21. Extending EuNEx

Adding a New Symbol

Define a new SymbolIndex_t constant in main.cpp
Create a MECoreActor for it, passing OEG, MDG, and CH actor IDs
Register it with oeGateway->mapSymbol(newSym, bookActor->getActorId())
Add it to AITraderActor's symbol list
Add seed orders if desired

Adding a New Actor

Create src/actors/MyActor.hpp inheriting tredzone::Actor
Register event handlers in constructor: registerEventHandler<EventT>(*this)
Create Event::Pipe members for each destination actor
Add .cpp to EUNEX_CORE_SOURCES in CMakeLists.txt
Wire into topology in main.cpp

Adding a New Event Type

Define the struct in src/actors/Events.hpp inheriting tredzone::Actor::Event
Add onEvent(const MyEvent&) to receiving actors
Register handler: registerEventHandler<MyEvent>(*this)
Push via pipe: pipe.push<MyEvent>(args...)

Adding a New Trading Strategy

Add enum value to Strategy in AITraderActor.hpp
Implement strategyMyStrategy() method
Add case to submitOrder() switch
Assign to desired members in initMembers()

Future Roadmap

 Current (v0.9.5)                  Planned
 ════════════════                  ═══════════════════════════════════

 ✓ Limit + Market + Stop orders    □ Pegged, Mid-Point, Iceberg
 ✓ IOC, FOK, Day                   □ GTD, GTC, VFU, VFCU
 ✓ Trading phases (PreOpen/CTS)    □ TAL, VDO, Reserved phases
 ✓ FIX 4.4 gateway                 □ FIX 5.0 SP2 + SBE binary
 ✓ Kafka Bus persistence           □ Kafka consumer replay
 ✓ SimplxShim (emulation)          □ Real Simplx multi-core
 ✓ 7 symbols (real prices)         □ Multi-segment, partitions
 ✓ Single partition                □ Cross-partition routing
 ✓ Clearing house + AI traders     □ EuroCCP/LCH integration
 ✓ IACA fragments                  □ IACA FINISH + COPY + IDS
 ✓ Python bridge (JSON)            □ SBE multicast MDG
 ✓ Market simulation (C++ + Py)    □ Multi-day backtesting
 ✓ Ticker tape + OHLCV charts      □ SATURN ARM (MiFID II RTS 22)
 ✓ Daily close persistence          □ PTB (Post-Trade Box)
 ✓ AI Analyst (Ollama/Groq/HF)
 ✓ LLM trading strategy (CH)
 ✓ Message Flow Visualizer
 ✓ Engine mode switch (Py ↔ C++)
 ✓ .env auto-loading config

Generated for EuNEx v0.9.5 — Euronext Optiq Architecture Simulator

EuNEx Developers Guide

Table of Contents

1. Overview

2. Architecture

High-Level System Diagram

3. Optiq Naming Alignment

4. Actor Topology

Core Affinity Layout

Event::Pipe Connections

5. Data Flow

Order Lifecycle (New Limit Order)

Market Data Flow

6. Core Components

6.1 SimplxShim — Actor Framework (src/engine/SimplxShim.hpp)

6.2 Types (src/common/Types.hpp)

6.3 Order & Trade Structs

7. Event System

Event::Pipe Usage Pattern

8. Order Book & Matching

Book (src/common/Book.hpp)

MECoreActor (src/actors/MECoreActor.hpp)

9. Recovery & IACA

RecoveryProxy (src/recovery/RecoveryProxy.hpp)

IACA Fragment Chains (src/iaca/IacaAggregator.hpp)

10. Kafka Bus

Overview

Topics

Architecture

Compile-Time Toggle

Runtime Configuration

Docker Deployment

11. FIX Protocol Gateway

FIXAcceptorActor (src/actors/FIXAcceptorActor.hpp)

12. Clearing House

ClearingHouseActor (src/actors/ClearingHouseActor.hpp)

13. AI Trading Members

AITraderActor (src/actors/AITraderActor.hpp)

14. Market Simulation

C++ Engine (AITraderActor)

Python Dashboard (MarketSimulator)

Seed Orders (Session Start)

Daily Close Persistence

Ticker Tape

OHLCV Candlestick Chart

15. AI Market Analyst

Provider Fallback Chain

Environment Variables

Prompt Template

API Endpoints

16. Developer Message Flow Visualizer

Pipeline Stages

Implementation

API

UI Features

17. Engine Mode Switch

Architecture

Switching Modes

Order Routing

FIX Message Flow (C++ Mode)

Connection Lifecycle

18. Project Structure

19. Build & Test

Prerequisites

Build Commands

CMake Options

Test Suites

20. Configuration

Runtime Configuration (main.cpp)

Seed Orders

21. Extending EuNEx

Adding a New Symbol

Adding a New Actor

Adding a New Event Type

Adding a New Trading Strategy

Future Roadmap

6.1 SimplxShim — Actor Framework (`src/engine/SimplxShim.hpp`)

6.2 Types (`src/common/Types.hpp`)

Book (`src/common/Book.hpp`)

MECoreActor (`src/actors/MECoreActor.hpp`)

RecoveryProxy (`src/recovery/RecoveryProxy.hpp`)

IACA Fragment Chains (`src/iaca/IacaAggregator.hpp`)

FIXAcceptorActor (`src/actors/FIXAcceptorActor.hpp`)

ClearingHouseActor (`src/actors/ClearingHouseActor.hpp`)

AITraderActor (`src/actors/AITraderActor.hpp`)