# chronoxor/cpptrader architecture

> Architecture diagram of the GitHub repository chronoxor/cpptrader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chronoxor/cpptrader
- Repository: https://github.com/chronoxor/cpptrader

## Overview

1. **What this repository is**
   CppTrader is a C++ trading-engine library focused on low-latency market data handling and order matching. The core deliverable is a reusable set of components rather than a monolithic application.

2. **Primary runtime subsystems**
   The codebase centers on two functional layers:
   - a **NASDAQ ITCH parser/handler** for ingesting market data messages
   - a **matching / market management layer** that maintains symbols, order books, price levels, and orders, and emits updates through a handler interface

3. **Library layout and code ownership**
   Public API headers live under `include/trader/...`, while implementations are split into `source/trader/...`. The `matching` namespace contains the core trading abstractions, and `providers/nasdaq` contains exchange-specific input handling. This is a classic header/public-API plus source/implementation split.

4. **Core matching model**
   The matching subsystem is built around a few key entities:
   - `order`
   - `level` / price level
   - `order_book`
   - `symbol`
   - `market_manager`
   - `update`
   - `errors`
   
   These form the data model and state transitions for add, modify, delete, and execute-style order events.

5. **Data flow through the trading engine**
   The typical flow is: incoming feed message → ITCH handler parses it → market manager applies the event → order book / levels / orders are updated → market updates are emitted to a consumer via a handler interface. That consumer boundary is important: the engine is designed to notify external code without embedding application logic.

6. **Exchange-specific adapter boundary**
   `include/trader/providers/nasdaq/itch_handler.h` and its source file are the main exchange adapter. It encapsulates parsing and dispatching NASDAQ ITCH messages, keeping exchange protocol logic separate from the generic matching engine.

7. **Performance-oriented architecture**
   The README shows three market-manager variants in `performance/`:
   - a baseline market manager
   - an optimized version using preallocated arrays, pooled levels, and cache-friendly storage
   - an aggressive version that removes more bookkeeping, including symbol maintenance and handler notifications
   
   This suggests the repository is explicitly designed to compare architectural tradeoffs between maintainability and latency/throughput.

8. **Examples as integration entry points**
   `examples/itch_handler.cpp`, `examples/market_manager.cpp`, and `examples/matching_engine.cpp` demonstrate the intended composition of the library components. They are useful as reference wiring for how parsing, matching, and external callbacks are connected.

9. **Tests and verification**
   `tests/` contains unit/integration coverage for the ITCH handler, market manager, and matching engine. This indicates the repo validates both protocol parsing and stateful order-book behavior, not just isolated utilities.

10. **Build, docs, and CI infrastructure**
    The project is CMake-based and cross-platform, with CI workflows for Linux, macOS, and multiple Windows toolchains. Doxygen documentation is part of the repo, and the `modules/` directory pulls in external build dependencies such as Catch2, benchmarking support, and utility libraries. The `gil` tool is used to resolve linked dependencies.

11. **Artifacts and reference data**
    `tools/itch/` contains the NASDAQ ITCH specification and sample feed data, while `tools/matching/` contains scenario files for exercising order-book behavior. These files support both correctness testing and benchmark reproducibility.

12. **How to think about the architecture diagram**
    The highest-value boxes to draw are:
    - external market data input
    - ITCH protocol handler
    - market manager / matching engine
    - order book, levels, orders, and symbols as internal state
    - update/notification boundary to downstream consumers
    - tests, examples, and benchmarks as separate consumers of the same library API

Main entry points: [`include/trader/matching/market_manager.h`](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/market_manager.h) (Market manager), [`source/trader/providers/nasdaq/itch_handler.cpp`](https://github.com/chronoxor/cpptrader/blob/master/source/trader/providers/nasdaq/itch_handler.cpp) (ITCH handler), [`include/trader/matching/order_book.h`](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/order_book.h) (Order book), [`tests/test_matching_engine.cpp`](https://github.com/chronoxor/cpptrader/blob/master/tests/test_matching_engine.cpp) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_itch_handler_api["ITCH API<br/>adapter header<br/>[itch_handler.h]"]
  node_market_handler_api["Market handler<br/>callback interface<br/>[market_handler.h]"]
  node_order_model["Order<br/>domain model<br/>[order.h]"]
  node_level_model["Level<br/>domain model<br/>[level.h]"]
  node_symbol_model["Symbol<br/>domain model<br/>[symbol.h]"]
  node_update_model["Update<br/>event model<br/>[update.h]"]
  node_errors_model["Errors<br/>status model<br/>[errors.h]"]
end

subgraph group_engine_core["Engine Core"]
  node_order_book[("Order book<br/>stateful book<br/>[order_book.h]")]
  node_market_manager["Market manager<br/>engine coordinator<br/>[market_manager.h]"]
  node_matching_impl["Matching impl<br/>engine source<br/>[market_manager.cpp]"]
  node_order_impl["Order impl<br/>engine source<br/>[order.cpp]"]
  node_order_book_impl["Book impl<br/>engine source<br/>[order_book.cpp]"]
end

subgraph group_exchange_adapter["Exchange Adapter"]
  node_itch_handler["ITCH handler<br/>protocol parser<br/>[itch_handler.cpp]"]
end

subgraph group_consumers["Consumers"]
  node_examples["Examples<br/>usage entry points"]
  node_tests["Tests<br/>verification suite"]
  node_performance["Performance<br/>bench variants<br/>[market_manager.cpp]"]
end

subgraph group_tooling["Tooling"]
  node_docs_data["Docs data<br/>reference assets<br/>[sample.itch]"]
  node_build_docs["Build docs<br/>tooling"]
end

node_external_feed(("Market data<br/>input"))

node_external_feed -->|"parse"| node_itch_handler
node_itch_handler -->|"dispatch"| node_market_manager
node_market_manager -->|"update"| node_order_book
node_order_book -->|"own"| node_order_model
node_order_book -->|"aggregate"| node_level_model
node_market_manager -->|"manage"| node_symbol_model
node_market_manager -->|"emit"| node_update_model
node_market_manager -->|"callback"| node_market_handler_api
node_market_manager -->|"report"| node_errors_model
node_itch_handler -->|"implements"| node_itch_handler_api
node_matching_impl -->|"implements"| node_market_manager
node_order_impl -->|"implements"| node_order_model
node_order_book_impl -->|"implements"| node_order_book
node_examples -->|"uses"| node_itch_handler_api
node_examples -->|"uses"| node_market_handler_api
node_tests -->|"verify"| node_itch_handler
node_tests -->|"verify"| node_market_manager
node_performance -->|"compare"| node_market_manager
node_docs_data -.->|"drive"| node_itch_handler
node_docs_data -.->|"scenario"| node_tests
node_build_docs -.->|"document"| node_itch_handler_api

click node_itch_handler_api "https://github.com/chronoxor/cpptrader/blob/master/include/trader/providers/nasdaq/itch_handler.h"
click node_market_handler_api "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/market_handler.h"
click node_order_model "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/order.h"
click node_level_model "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/level.h"
click node_symbol_model "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/symbol.h"
click node_update_model "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/update.h"
click node_errors_model "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/errors.h"
click node_order_book "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/order_book.h"
click node_market_manager "https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/market_manager.h"
click node_matching_impl "https://github.com/chronoxor/cpptrader/blob/master/source/trader/matching/market_manager.cpp"
click node_order_impl "https://github.com/chronoxor/cpptrader/blob/master/source/trader/matching/order.cpp"
click node_order_book_impl "https://github.com/chronoxor/cpptrader/blob/master/source/trader/matching/order_book.cpp"
click node_itch_handler "https://github.com/chronoxor/cpptrader/blob/master/source/trader/providers/nasdaq/itch_handler.cpp"
click node_examples "https://github.com/chronoxor/cpptrader/blob/master/examples/matching_engine.cpp"
click node_tests "https://github.com/chronoxor/cpptrader/blob/master/tests/test_matching_engine.cpp"
click node_performance "https://github.com/chronoxor/cpptrader/blob/master/performance/market_manager.cpp"
click node_docs_data "https://github.com/chronoxor/cpptrader/blob/master/tools/itch/sample.itch"
click node_build_docs "https://github.com/chronoxor/cpptrader/tree/master/documents/Doxyfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_itch_handler_api,node_market_handler_api,node_order_model,node_level_model,node_symbol_model,node_update_model,node_errors_model toneBlue
class node_order_book,node_market_manager,node_matching_impl,node_order_impl,node_order_book_impl toneAmber
class node_itch_handler toneMint
class node_examples,node_tests,node_performance toneRose
class node_docs_data,node_build_docs toneIndigo
class node_external_feed toneNeutral
```

## Components

### Public API

Headers that define the reusable trading library interface.

- [ITCH API](https://github.com/chronoxor/cpptrader/blob/master/include/trader/providers/nasdaq/itch_handler.h): adapter header · Public NASDAQ ITCH handler interface. · `include/trader/providers/nasdaq/itch_handler.h`
- [Market handler](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/market_handler.h): callback interface · Consumer-facing handler boundary for emitted market updates. · `include/trader/matching/market_handler.h`
- [Order](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/order.h): domain model · Order state and mutation rules. · `include/trader/matching/order.h`
- [Level](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/level.h): domain model · Price-level aggregation and book depth state. · `include/trader/matching/level.h`
- [Symbol](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/symbol.h): domain model · Instrument identity and per-symbol state. · `include/trader/matching/symbol.h`
- [Update](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/update.h): event model · Normalized market update emitted from the engine. · `include/trader/matching/update.h`
- [Errors](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/errors.h): status model · Matching and protocol error definitions. · `include/trader/matching/errors.h`

### Engine Core

Matching engine state, models, and implementation.

- [Order book](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/order_book.h): stateful book · Per-symbol book that owns levels and orders. · `include/trader/matching/order_book.h`
- [Market manager](https://github.com/chronoxor/cpptrader/blob/master/include/trader/matching/market_manager.h): engine coordinator · Applies events, updates books, and coordinates symbol-level state. · `include/trader/matching/market_manager.h`
- [Matching impl](https://github.com/chronoxor/cpptrader/blob/master/source/trader/matching/market_manager.cpp): engine source · Source-side implementation of order, book, and manager behavior. · `source/trader/matching/market_manager.cpp`
- [Order impl](https://github.com/chronoxor/cpptrader/blob/master/source/trader/matching/order.cpp): engine source · Source implementation for order state transitions and helpers. · `source/trader/matching/order.cpp`
- [Book impl](https://github.com/chronoxor/cpptrader/blob/master/source/trader/matching/order_book.cpp): engine source · Source implementation for order book maintenance. · `source/trader/matching/order_book.cpp`

### Exchange Adapter

NASDAQ-specific feed ingestion and dispatch.

- [ITCH handler](https://github.com/chronoxor/cpptrader/blob/master/source/trader/providers/nasdaq/itch_handler.cpp): protocol parser · NASDAQ ITCH parser and dispatcher. · `source/trader/providers/nasdaq/itch_handler.cpp`

### Consumers

Examples, tests, and benchmark-style entry points that exercise the library.

- [Examples](https://github.com/chronoxor/cpptrader/blob/master/examples/matching_engine.cpp): usage entry points · Reference wiring for parser, matching engine, and callbacks. · `examples/matching_engine.cpp`
- [Tests](https://github.com/chronoxor/cpptrader/blob/master/tests/test_matching_engine.cpp): verification suite · Unit and integration coverage for parsing and matching behavior. · `tests/test_matching_engine.cpp`
- [Performance](https://github.com/chronoxor/cpptrader/blob/master/performance/market_manager.cpp): bench variants · Baseline and optimized market-manager implementations for comparison. · `performance/market_manager.cpp`

### Tooling

Docs, scenario data, and external dependency wiring.

- [Docs data](https://github.com/chronoxor/cpptrader/blob/master/tools/itch/sample.itch): reference assets · ITCH specification, sample feed, and matching scenarios. · `tools/itch/sample.itch`
- [Build docs](https://github.com/chronoxor/cpptrader/tree/master/documents/Doxyfile): tooling · CMake, module wiring, and Doxygen documentation setup. · `documents/Doxyfile`

### Other components

- **Market data**: input · Incoming NASDAQ ITCH feed or sample data entering the library.

## Connections

- Market data → ITCH handler: parse · Feed messages are parsed by the NASDAQ ITCH adapter.
- ITCH handler → Market manager: dispatch · Parsed protocol events are forwarded into the trading engine.
- Market manager → Order book: update · Manager mutates per-symbol books and levels.
- Order book → Order: own · Books track individual orders.
- Order book → Level: aggregate · Books maintain price levels.
- Market manager → Symbol: manage · Manager coordinates symbol lifecycle and lookup.
- Market manager → Update: emit · Normalized updates are produced for downstream consumers.
- Market manager → Market handler: callback · Consumer handler receives updates and notifications.
- Market manager → Errors: report · Failures and edge cases surface through matching error types.
- ITCH handler → ITCH API: implements · Source implementation realizes the public adapter contract.
- Matching impl → Market manager: implements · Source implementation backs the public manager API.
- Order impl → Order: implements · Source-side behavior for order state.
- Book impl → Order book: implements · Source-side behavior for order book maintenance.
- Examples → ITCH API: uses · Examples show how to wire feed parsing.
- Examples → Market handler: uses · Examples demonstrate the consumer callback boundary.
- Tests → ITCH handler: verify · Tests exercise protocol parsing and dispatch.
- Tests → Market manager: verify · Tests validate matching and state transitions.
- Performance → Market manager: compare · Benchmark variants contrast manager design tradeoffs.
- Docs data → ITCH handler: drive · Specification and sample feed inform protocol handling.
- Docs data → Tests: scenario · Matching scenarios support validation coverage.
- Build docs → ITCH API: document · Public headers are documented and built through the tooling setup.
