# aryan0dhankhar/lob_engine architecture

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

- Interactive diagram: https://gitdiagram.com/aryan0dhankhar/lob_engine
- Repository: https://github.com/aryan0dhankhar/lob_engine

## Overview

This is a C++ limit-order-book engine: a Python market-feed simulator sends UDP packets to the engine, which parses add/cancel messages, transfers requests through an SPSC queue, and updates the order book. The README documents asynchronous logging; source excerpts show its queue-backed worker writing to a log file. The order book uses a preallocated pool and shared order/price-level types. The excerpts do not show the engine invoking `match()`, so the graph does not claim that crossing orders are matched during the main workflow.

Main entry points: [`main.cpp`](https://github.com/aryan0dhankhar/lob_engine/blob/main/main.cpp) (Engine runtime), [`include/FeedHandler.hpp`](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/FeedHandler.hpp) (Packet gateway), [`src/OrderBook.cpp`](https://github.com/aryan0dhankhar/lob_engine/blob/main/src/OrderBook.cpp) (Limit order book), [`src/Logger.cpp`](https://github.com/aryan0dhankhar/lob_engine/blob/main/src/Logger.cpp) (Async logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Market-data ingress"]
  node_feed["Feed simulator<br/>[market_feed.py]"]
  node_socket["UDP socket<br/>[UdpSocket.hpp]"]
  node_gateway["Packet gateway<br/>[FeedHandler.hpp]"]
  node_wiretypes["Wire messages<br/>[MarketData.hpp]"]
end

subgraph group_engine["Order processing"]
  node_runtime["Engine runtime<br/>[main.cpp]"]
  node_requests["Order requests<br/>[MarketData.hpp]"]
  node_queue["SPSC queue<br/>[LockFreeQueue.hpp]"]
  node_book["Limit order book<br/>[OrderBook.cpp]"]
end

subgraph group_internals["Engine internals"]
  node_pool["Order object pool<br/>[ObjectPool.hpp]"]
  node_domain["Order types<br/>[Types.hpp]"]
  node_book_api["Order book API<br/>[OrderBook.hpp]"]
end

subgraph group_observability["Logging"]
  node_logger["Async logger<br/>[Logger.cpp]"]
  node_logqueue["Log queue<br/>[LockFreeQueue.hpp]"]
  node_logfile["Log file"]
end

node_udp(("UDP multicast"))

node_feed -.->|"sends packets"| node_udp
node_udp -.->|"delivers datagrams"| node_socket
node_runtime -->|"receives datagrams"| node_socket
node_runtime -->|"processes packets"| node_gateway
node_gateway -->|"parses messages"| node_wiretypes
node_gateway -->|"pushes requests"| node_queue
node_gateway -->|"builds requests"| node_requests
node_runtime -->|"pops requests"| node_queue
node_runtime -->|"adds or cancels"| node_book
node_book -->|"allocates orders"| node_pool
node_book -->|"stores order types"| node_domain
node_runtime -->|"starts and logs"| node_logger
node_logger -->|"enqueues messages"| node_logqueue
node_logger -->|"writes log lines"| node_logfile

click node_feed "https://github.com/aryan0dhankhar/lob_engine/blob/main/market_feed.py"
click node_socket "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/UdpSocket.hpp"
click node_gateway "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/FeedHandler.hpp"
click node_wiretypes "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/MarketData.hpp"
click node_runtime "https://github.com/aryan0dhankhar/lob_engine/blob/main/main.cpp"
click node_requests "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/MarketData.hpp"
click node_queue "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/LockFreeQueue.hpp"
click node_book "https://github.com/aryan0dhankhar/lob_engine/blob/main/src/OrderBook.cpp"
click node_pool "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/ObjectPool.hpp"
click node_domain "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/Types.hpp"
click node_book_api "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/OrderBook.hpp"
click node_logger "https://github.com/aryan0dhankhar/lob_engine/blob/main/src/Logger.cpp"
click node_logqueue "https://github.com/aryan0dhankhar/lob_engine/blob/main/include/LockFreeQueue.hpp"

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_feed,node_socket,node_gateway,node_wiretypes toneBlue
class node_runtime,node_requests,node_queue,node_book toneAmber
class node_pool,node_domain,node_book_api toneMint
class node_logger,node_logqueue,node_logfile toneRose
class node_udp toneIndigo
```

## Components

### Market-data ingress

- [Feed simulator](https://github.com/aryan0dhankhar/lob_engine/blob/main/market_feed.py): `market_feed.py`
- [UDP socket](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/UdpSocket.hpp): `include/UdpSocket.hpp`
- [Packet gateway](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/FeedHandler.hpp): `include/FeedHandler.hpp`
- [Wire messages](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/MarketData.hpp): `include/MarketData.hpp`

### Order processing

- [Engine runtime](https://github.com/aryan0dhankhar/lob_engine/blob/main/main.cpp): `main.cpp`
- [Order requests](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/MarketData.hpp): `include/MarketData.hpp`
- [SPSC queue](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/LockFreeQueue.hpp): `include/LockFreeQueue.hpp`
- [Limit order book](https://github.com/aryan0dhankhar/lob_engine/blob/main/src/OrderBook.cpp): `src/OrderBook.cpp`

### Engine internals

- [Order object pool](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/ObjectPool.hpp): `include/ObjectPool.hpp`
- [Order types](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/Types.hpp): `include/Types.hpp`
- [Order book API](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/OrderBook.hpp): `include/OrderBook.hpp`

### Logging

- [Async logger](https://github.com/aryan0dhankhar/lob_engine/blob/main/src/Logger.cpp): `src/Logger.cpp`
- [Log queue](https://github.com/aryan0dhankhar/lob_engine/blob/main/include/LockFreeQueue.hpp): `include/LockFreeQueue.hpp`
- **Log file**

### Other components

- **UDP multicast**

## Connections

- Feed simulator → UDP multicast: sends packets (evidence: `README.md`)
- UDP multicast → UDP socket: delivers datagrams (evidence: `README.md`)
- Engine runtime → UDP socket: receives datagrams (evidence: `main.cpp`)
- Engine runtime → Packet gateway: processes packets (evidence: `main.cpp`)
- Packet gateway → Wire messages: parses messages (evidence: `include/FeedHandler.hpp`)
- Packet gateway → SPSC queue: pushes requests (evidence: `include/FeedHandler.hpp`)
- Packet gateway → Order requests: builds requests (evidence: `include/FeedHandler.hpp`)
- Engine runtime → SPSC queue: pops requests (evidence: `main.cpp`)
- Engine runtime → Limit order book: adds or cancels (evidence: `main.cpp`)
- Limit order book → Order object pool: allocates orders (evidence: `src/OrderBook.cpp`)
- Limit order book → Order types: stores order types
- Engine runtime → Async logger: starts and logs (evidence: `main.cpp`)
- Async logger → Log queue: enqueues messages (evidence: `src/Logger.cpp`)
- Async logger → Log file: writes log lines (evidence: `src/Logger.cpp`)
