# mike-here/nexuslob architecture

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

- Interactive diagram: https://gitdiagram.com/mike-here/nexuslob
- Repository: https://github.com/mike-here/nexuslob

## Overview

NexusLOB is a single-writer limit-order-book and matching engine exposed through a fixed-size binary TCP protocol. A client submits orders and cancellations; the epoll listener decodes messages into an ingress ring, the pinned matching loop processes them, and execution reports return through an egress ring to the client. The book handles crossing, price-time fills, resting orders, and cancellation. The README also documents a NumPy momentum workload and execution validator. Relationships shown are supported by the README or excerpts; unsampled implementation details are omitted.

Main entry points: [`src/network_listener.cpp`](https://github.com/mike-here/nexuslob/blob/main/src/network_listener.cpp) (epoll listener), [`src/order_book.cpp`](https://github.com/mike-here/nexuslob/blob/main/src/order_book.cpp) (Order book), [`src/main.cpp`](https://github.com/mike-here/nexuslob/blob/main/src/main.cpp) (Matching loop), [`include/nexuslob/network_listener.h`](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/network_listener.h) (Listener API and rings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tcp["TCP interface"]
  node_listener["epoll listener"]
  node_wire["Binary protocol<br/>[wire_protocol.h]"]
end

subgraph group_matching["Matching engine"]
  node_main["Matching loop<br/>[main.cpp]"]
  node_book["Order book<br/>[order_book.cpp]"]
  node_price["Price-level books<br/>[order_book.h]"]
  node_pool["Order pool<br/>[memory_pool.h]"]
  node_types["Order and execution types<br/>[types.h]"]
end

subgraph group_transport["Thread transport"]
  node_ingress["Ingress SPSC ring<br/>[ring_buffer.h]"]
  node_egress["Egress SPSC ring<br/>[ring_buffer.h]"]
  node_listener_api["Listener API and rings<br/>[network_listener.h]"]
end

subgraph group_workload["Workload replay"]
  node_backtest["Momentum workload"]
end

node_client(("TCP client"))

node_client -->|"sends orders"| node_listener
node_listener -->|"decodes and encodes"| node_wire
node_listener -->|"queues messages"| node_ingress
node_main -->|"starts thread"| node_listener
node_main -->|"reads messages"| node_ingress
node_main -->|"processes messages"| node_book
node_book -->|"publishes executions"| node_egress
node_listener -->|"drains reports"| node_egress
node_book -->|"updates price levels"| node_price
node_book -->|"allocates resting orders"| node_pool
node_book -->|"processes typed messages"| node_types
node_listener -->|"implements listener"| node_listener_api
node_listener_api -->|"defines ring type"| node_ingress
node_listener_api -->|"defines ring type"| node_egress
node_backtest -->|"connects and validates"| node_client

click node_listener "https://github.com/mike-here/nexuslob/blob/main/src/network_listener.cpp"
click node_wire "https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/wire_protocol.h"
click node_main "https://github.com/mike-here/nexuslob/blob/main/src/main.cpp"
click node_book "https://github.com/mike-here/nexuslob/blob/main/src/order_book.cpp"
click node_price "https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/order_book.h"
click node_pool "https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/memory_pool.h"
click node_types "https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/types.h"
click node_ingress "https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/ring_buffer.h"
click node_egress "https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/ring_buffer.h"
click node_listener_api "https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/network_listener.h"
click node_backtest "https://github.com/mike-here/nexuslob/blob/main/tools/backtest_momentum.py"

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_listener,node_wire,node_client toneBlue
class node_main,node_book,node_price,node_pool,node_types toneAmber
class node_ingress,node_egress,node_listener_api toneMint
class node_backtest toneRose
```

## Components

### TCP interface

- [epoll listener](https://github.com/mike-here/nexuslob/blob/main/src/network_listener.cpp): `src/network_listener.cpp`
- [Binary protocol](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/wire_protocol.h): `include/nexuslob/wire_protocol.h`

### Matching engine

- [Matching loop](https://github.com/mike-here/nexuslob/blob/main/src/main.cpp): `src/main.cpp`
- [Order book](https://github.com/mike-here/nexuslob/blob/main/src/order_book.cpp): `src/order_book.cpp`
- [Price-level books](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/order_book.h): `include/nexuslob/order_book.h`
- [Order pool](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/memory_pool.h): `include/nexuslob/memory_pool.h`
- [Order and execution types](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/types.h): `include/nexuslob/types.h`

### Thread transport

- [Ingress SPSC ring](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/ring_buffer.h): `include/nexuslob/ring_buffer.h`
- [Egress SPSC ring](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/ring_buffer.h): `include/nexuslob/ring_buffer.h`
- [Listener API and rings](https://github.com/mike-here/nexuslob/blob/main/include/nexuslob/network_listener.h): `include/nexuslob/network_listener.h`

### Workload replay

- [Momentum workload](https://github.com/mike-here/nexuslob/blob/main/tools/backtest_momentum.py): `tools/backtest_momentum.py`

### Other components

- **TCP client**

## Connections

- TCP client → epoll listener: sends orders (evidence: `README.md`)
- epoll listener → Binary protocol: decodes and encodes (evidence: `src/network_listener.cpp`)
- epoll listener → Ingress SPSC ring: queues messages (evidence: `src/network_listener.cpp`)
- Matching loop → epoll listener: starts thread (evidence: `src/main.cpp`)
- Matching loop → Ingress SPSC ring: reads messages (evidence: `src/main.cpp`)
- Matching loop → Order book: processes messages (evidence: `src/main.cpp`)
- Order book → Egress SPSC ring: publishes executions
- epoll listener → Egress SPSC ring: drains reports (evidence: `src/network_listener.cpp`)
- Order book → Price-level books: updates price levels (evidence: `src/order_book.cpp`)
- Order book → Order pool: allocates resting orders
- Order book → Order and execution types: processes typed messages (evidence: `src/order_book.cpp`)
- epoll listener → Listener API and rings: implements listener (evidence: `src/network_listener.cpp`)
- Listener API and rings → Ingress SPSC ring: defines ring type (evidence: `include/nexuslob/network_listener.h`)
- Listener API and rings → Egress SPSC ring: defines ring type (evidence: `include/nexuslob/network_listener.h`)
- Momentum workload → TCP client: connects and validates (evidence: `README.md`)
