How brprojects/limit-order-book works
1. Repository purpose
- This is a self-contained C++ limit order book / matching engine project.
- The central product is the trading core; the rest of the repo supports synthetic order generation, latency measurement, analysis, and automated testing.
2. Top-level subsystems
- Limit_Order_Book/: core matching engine and in-memory book representation.
- Generate_Orders/: synthetic workload generator for test input.
- Process_Orders/: order replay, latency capture, and post-processing/visualization.
- test/: GoogleTest-based unit and integration tests.
- main.cpp: application entry point for running the system.
3. Core domain model
- The engine models three main entities: Order, Limit, and Book.
- Order is the atomic request object, with identity, side, size, price, and list links.
- Limit represents one price level and holds a FIFO queue of orders at that price.
- Book owns the full state for both sides of the market plus stop-order state.
4. Book data structure and performance boundary
- The visible architecture is an AVL-tree-based price ladder on each side of the book.
- Buy and sell price levels are stored separately, each as a balanced tree of Limit nodes.
- Each Limit contains a doubly linked list of Order objects, preserving FIFO within the same price.
- The design optimizes for constant-time best bid/offer lookup via cached pointers to the current top-of-book nodes.
5. Order lookup and mutation model
- Orders are also indexed by ID, enabling O(1) cancel and modify operations once the order is found.
- Limits are indexed by price so that adding an order to an existing price level is cheap, while first insertion at a new price level costs tree work.
- The architecture is tuned around the common trading-engine boundary: many requests enter, but matching itself is sequential.
6. Matching and execution flow
- Incoming requests are processed by the Book logic, which decides whether they add liquidity, remove liquidity, or trigger execution.
- Market and market-crossing limit orders consume from the opposite side of the book using price priority plus FIFO within each level.
- Executions can cascade across multiple orders and may delete empty price levels, which in turn can rebalance the AVL trees.
- This makes execution path latency strongly dependent on both trade count and tree maintenance cost.
7. Stop and stop-limit handling
- Stop and stop-limit orders are stored separately from active book orders in dedicated stop-side trees.
- When the market crosses a stop price, those orders are activated and converted into market or limit behavior.
- This is an important architectural boundary: active liquidity and latent conditional orders are maintained in different structures until trigger time.
8. Synthetic workload generation
- Generate_Orders exists to create realistic test order streams rather than live exchange feeds.
- The generator starts from a seeded initial book and produces millions of requests with a statistical price distribution.
- Its output feeds the performance pipeline, providing repeatable workloads for throughput and latency measurement.
9. Processing, timing, and analysis pipeline
- Process_Orders is the measurement layer around the core engine.
- It records per-request processing times into order_processing_times.csv, then uses data_visualisation.py to analyze latency distributions and correlations.
- This subsystem is separate from the matching engine itself, which keeps performance instrumentation from polluting the core matching logic.
10. Testing boundary
- The test/ directory uses GoogleTest to validate correctness of order behavior and book state transitions.
- There are tests for example orders and for the limit order book internals, giving both scenario coverage and structural coverage.
- This is the repo’s main safety net for the sequential matching logic and edge cases around add/modify/cancel/trigger flows.
11. Build and integration model
- The project is built with CMake, with the core engine, generator, processing utilities, and tests all organized as separate build targets.
- The codebase is predominantly native C++, while Python is only used for offline visualization, not for matching or execution.
12. How the pieces fit together
- The overall data flow is: generate synthetic orders → feed them into the matching engine → record latency and execution outcomes → analyze results offline → validate correctness with tests.
- The architectural center is the Book, and every other subsystem exists either to supply it workload, observe it, or verify it.
Main entry points: Book.hpp Book · CMakeLists.txt Build · GenerateOrders.cpp Generator · OrderPipeline.cpp Pipeline
Components 15
Root
Build entrypoints and app wiring
Matching Core
Limit order book and in-memory market state
Order Generation
Synthetic workload creation
Order Processing
Replay, timing, and analysis
- Pipeline · Order replay and latency capture logic
Process_Orders/OrderPipeline.cpp - Pipeline API · Processing pipeline interface
Process_Orders/OrderPipeline.hpp - Timings · Per-order processing time output
Process_Orders/order_processing_times.csv - Visualiser · Offline latency analysis and plotting
Process_Orders/data_visualisation.py
Tests
Correctness coverage
- Test Build · Test target configuration
test/CMakeLists.txt - Examples · Scenario-based order behavior tests
test/ExampleOrdersTests.cpp - Book Tests · Limit order book state and transition tests
test/LimitOrderBookTests.cpp
Connections 19
- Main → Book: runs engine · Application entry uses the matching core
- Build → Main: builds · Top-level build includes the app entry
- Build → Generator: builds · Build targets include the generator
- Build → Pipeline: builds · Build targets include the processing layer
- Build → Test Build: enables tests · Top-level build wires in the test project
- Book → Order: manages · Book owns and mutates orders
- Book → Limit: organizes · Book maintains price levels as limits
- Limit → Order: queues · Each limit holds a FIFO list of orders
- Generator → Gen API: uses API · Generator implementation depends on its interface
- Generator → Seed Book: seeds from · Workload generation starts from a seeded book
- Generator → Book: feeds orders · Synthetic requests are intended for the matching engine
- Pipeline → Pipeline API: uses API · Processing implementation depends on its interface
- Pipeline → Book: replays through · Pipeline measures the core matching engine
- Pipeline → Timings: writes · Latency measurements are recorded to CSV
- Visualiser → Timings: analyzes · Visualization script consumes timing output
- Examples → Book: validates · Scenario tests cover behavior across the book
- Book Tests → Book: validates · Internal tests exercise book transitions and edge cases
- Test Build → Examples: builds · Test build includes example scenarios
- Test Build → Book Tests: builds · Test build includes core book tests