How chronoxor/cpptrader works
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: market_manager.h Market manager · itch_handler.cpp ITCH handler · order_book.h Order book · test_matching_engine.cpp Tests
Components 19
Public API
Headers that define the reusable trading library interface.
- ITCH API · Public NASDAQ ITCH handler interface.
include/trader/providers/nasdaq/itch_handler.h - Market handler · Consumer-facing handler boundary for emitted market updates.
include/trader/matching/market_handler.h - Order · Order state and mutation rules.
include/trader/matching/order.h - Level · Price-level aggregation and book depth state.
include/trader/matching/level.h - Symbol · Instrument identity and per-symbol state.
include/trader/matching/symbol.h - Update · Normalized market update emitted from the engine.
include/trader/matching/update.h - Errors · Matching and protocol error definitions.
include/trader/matching/errors.h
Engine Core
Matching engine state, models, and implementation.
- Order book · Per-symbol book that owns levels and orders.
include/trader/matching/order_book.h - Market manager · Applies events, updates books, and coordinates symbol-level state.
include/trader/matching/market_manager.h - Matching impl · Source-side implementation of order, book, and manager behavior.
source/trader/matching/market_manager.cpp - Order impl · Source implementation for order state transitions and helpers.
source/trader/matching/order.cpp - Book impl · Source implementation for order book maintenance.
source/trader/matching/order_book.cpp
Exchange Adapter
NASDAQ-specific feed ingestion and dispatch.
- ITCH handler · 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 · Reference wiring for parser, matching engine, and callbacks.
examples/matching_engine.cpp - Tests · Unit and integration coverage for parsing and matching behavior.
tests/test_matching_engine.cpp - Performance · Baseline and optimized market-manager implementations for comparison.
performance/market_manager.cpp
Tooling
Docs, scenario data, and external dependency wiring.
- Docs data · ITCH specification, sample feed, and matching scenarios.
tools/itch/sample.itch - Build docs · CMake, module wiring, and Doxygen documentation setup.
documents/Doxyfile
Other components
- Market data · Incoming NASDAQ ITCH feed or sample data entering the library.
Connections 21
- 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.