# brprojects/limit-order-book architecture

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

- Interactive diagram: https://gitdiagram.com/brprojects/limit-order-book
- Repository: https://github.com/brprojects/limit-order-book

## Overview

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: [`Limit_Order_Book/Book.hpp`](https://github.com/brprojects/limit-order-book/blob/main/Limit_Order_Book/Book.hpp) (Book), [`CMakeLists.txt`](https://github.com/brprojects/limit-order-book/blob/main/CMakeLists.txt) (Build), [`Generate_Orders/GenerateOrders.cpp`](https://github.com/brprojects/limit-order-book/blob/main/Generate_Orders/GenerateOrders.cpp) (Generator), [`Process_Orders/OrderPipeline.cpp`](https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/OrderPipeline.cpp) (Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Root"]
  node_main_cpp["Main<br/>app entry<br/>[main.cpp]"]
  node_cmake_root["Build<br/>cmake root<br/>[CMakeLists.txt]"]
end

subgraph group_core["Matching Core"]
  node_book[("Book<br/>matching engine<br/>[Book.hpp]")]
  node_order["Order<br/>domain object<br/>[Order.hpp]"]
  node_limit{{"Limit<br/>price level<br/>[Limit.hpp]"}}
end

subgraph group_generation["Order Generation"]
  node_generate_orders_cpp["Generator<br/>workload producer<br/>[GenerateOrders.cpp]"]
  node_generate_orders_hpp["Gen API<br/>generator API<br/>[GenerateOrders.hpp]"]
  node_initial_orders["Seed Book<br/>input data<br/>[initialOrders.txt]"]
end

subgraph group_processing["Order Processing"]
  node_order_pipeline_cpp["Pipeline<br/>replay/timing<br/>[OrderPipeline.cpp]"]
  node_order_pipeline_hpp["Pipeline API<br/>processing API<br/>[OrderPipeline.hpp]"]
  node_order_times_csv["Timings<br/>measurement data"]
  node_visualisation_py["Visualiser<br/>analysis script"]
end

subgraph group_tests["Tests"]
  node_cmake_test["Test Build<br/>cmake test<br/>[CMakeLists.txt]"]
  node_example_tests["Examples<br/>gtest scenarios"]
  node_lob_tests["Book Tests<br/>gtest internals"]
end

node_main_cpp -->|"runs engine"| node_book
node_cmake_root -->|"builds"| node_main_cpp
node_cmake_root -->|"builds"| node_generate_orders_cpp
node_cmake_root -->|"builds"| node_order_pipeline_cpp
node_cmake_root -->|"enables tests"| node_cmake_test
node_book -->|"manages"| node_order
node_book -->|"organizes"| node_limit
node_limit -->|"queues"| node_order
node_generate_orders_cpp -->|"uses API"| node_generate_orders_hpp
node_generate_orders_cpp -->|"seeds from"| node_initial_orders
node_generate_orders_cpp -->|"feeds orders"| node_book
node_order_pipeline_cpp -->|"uses API"| node_order_pipeline_hpp
node_order_pipeline_cpp -->|"replays through"| node_book
node_order_pipeline_cpp -->|"writes"| node_order_times_csv
node_visualisation_py -->|"analyzes"| node_order_times_csv
node_example_tests -->|"validates"| node_book
node_lob_tests -->|"validates"| node_book
node_cmake_test -->|"builds"| node_example_tests
node_cmake_test -->|"builds"| node_lob_tests

click node_main_cpp "https://github.com/brprojects/limit-order-book/blob/main/main.cpp"
click node_cmake_root "https://github.com/brprojects/limit-order-book/blob/main/CMakeLists.txt"
click node_cmake_test "https://github.com/brprojects/limit-order-book/blob/main/test/CMakeLists.txt"
click node_book "https://github.com/brprojects/limit-order-book/blob/main/Limit_Order_Book/Book.hpp"
click node_order "https://github.com/brprojects/limit-order-book/blob/main/Limit_Order_Book/Order.hpp"
click node_limit "https://github.com/brprojects/limit-order-book/blob/main/Limit_Order_Book/Limit.hpp"
click node_generate_orders_cpp "https://github.com/brprojects/limit-order-book/blob/main/Generate_Orders/GenerateOrders.cpp"
click node_generate_orders_hpp "https://github.com/brprojects/limit-order-book/blob/main/Generate_Orders/GenerateOrders.hpp"
click node_initial_orders "https://github.com/brprojects/limit-order-book/blob/main/Generate_Orders/initialOrders.txt"
click node_order_pipeline_cpp "https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/OrderPipeline.cpp"
click node_order_pipeline_hpp "https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/OrderPipeline.hpp"
click node_order_times_csv "https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/order_processing_times.csv"
click node_visualisation_py "https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/data_visualisation.py"
click node_example_tests "https://github.com/brprojects/limit-order-book/blob/main/test/ExampleOrdersTests.cpp"
click node_lob_tests "https://github.com/brprojects/limit-order-book/blob/main/test/LimitOrderBookTests.cpp"

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_main_cpp,node_cmake_root toneBlue
class node_book,node_order,node_limit toneAmber
class node_generate_orders_cpp,node_generate_orders_hpp,node_initial_orders toneMint
class node_order_pipeline_cpp,node_order_pipeline_hpp,node_order_times_csv,node_visualisation_py toneRose
class node_cmake_test,node_example_tests,node_lob_tests toneIndigo
```

## Components

### Root

Build entrypoints and app wiring

- [Main](https://github.com/brprojects/limit-order-book/blob/main/main.cpp): app entry · Application entry point · `main.cpp`
- [Build](https://github.com/brprojects/limit-order-book/blob/main/CMakeLists.txt): cmake root · Top-level build configuration · `CMakeLists.txt`

### Matching Core

Limit order book and in-memory market state

- [Book](https://github.com/brprojects/limit-order-book/blob/main/Limit_Order_Book/Book.hpp): matching engine · Active book state, matching, execution, and stop-order handling · `Limit_Order_Book/Book.hpp`
- [Order](https://github.com/brprojects/limit-order-book/blob/main/Limit_Order_Book/Order.hpp): domain object · Atomic order record with identity, side, size, price, and links · `Limit_Order_Book/Order.hpp`
- [Limit](https://github.com/brprojects/limit-order-book/blob/main/Limit_Order_Book/Limit.hpp): price level · FIFO queue at one price level · `Limit_Order_Book/Limit.hpp`

### Order Generation

Synthetic workload creation

- [Generator](https://github.com/brprojects/limit-order-book/blob/main/Generate_Orders/GenerateOrders.cpp): workload producer · Synthetic order stream generator · `Generate_Orders/GenerateOrders.cpp`
- [Gen API](https://github.com/brprojects/limit-order-book/blob/main/Generate_Orders/GenerateOrders.hpp): generator API · Generator interface and configuration · `Generate_Orders/GenerateOrders.hpp`
- [Seed Book](https://github.com/brprojects/limit-order-book/blob/main/Generate_Orders/initialOrders.txt): input data · Seed order set used to start generation · `Generate_Orders/initialOrders.txt`

### Order Processing

Replay, timing, and analysis

- [Pipeline](https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/OrderPipeline.cpp): replay/timing · Order replay and latency capture logic · `Process_Orders/OrderPipeline.cpp`
- [Pipeline API](https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/OrderPipeline.hpp): processing API · Processing pipeline interface · `Process_Orders/OrderPipeline.hpp`
- [Timings](https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/order_processing_times.csv): measurement data · Per-order processing time output · `Process_Orders/order_processing_times.csv`
- [Visualiser](https://github.com/brprojects/limit-order-book/blob/main/Process_Orders/data_visualisation.py): analysis script · Offline latency analysis and plotting · `Process_Orders/data_visualisation.py`

### Tests

Correctness coverage

- [Test Build](https://github.com/brprojects/limit-order-book/blob/main/test/CMakeLists.txt): cmake test · Test target configuration · `test/CMakeLists.txt`
- [Examples](https://github.com/brprojects/limit-order-book/blob/main/test/ExampleOrdersTests.cpp): gtest scenarios · Scenario-based order behavior tests · `test/ExampleOrdersTests.cpp`
- [Book Tests](https://github.com/brprojects/limit-order-book/blob/main/test/LimitOrderBookTests.cpp): gtest internals · Limit order book state and transition tests · `test/LimitOrderBookTests.cpp`

## Connections

- 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
