# zenithsoulx/mercury architecture

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

- Interactive diagram: https://gitdiagram.com/zenithsoulx/mercury
- Repository: https://github.com/zenithsoulx/mercury

## Overview

Mercury replays LOBSTER market messages into a price-time-priority order book, with an optional path for comparing reconstructed states against reference snapshots and tooling for latency measurement. The graph follows the documented replay and matching layers, then shows the validation branch. Relationships among the core layers are documented in the README; validation wiring is also visible in the sampled validator entry point. Latency tooling is documented, but its detailed runtime behavior was not sampled.

Main entry points: [`src/order_book.cpp`](https://github.com/zenithsoulx/mercury/blob/main/src/order_book.cpp) (Order Book), [`src/replay_engine.cpp`](https://github.com/zenithsoulx/mercury/blob/main/src/replay_engine.cpp) (Replay Engine), [`tools/validate_replay.cpp`](https://github.com/zenithsoulx/mercury/blob/main/tools/validate_replay.cpp) (Validation CLI), [`src/book_validator.cpp`](https://github.com/zenithsoulx/mercury/blob/main/src/book_validator.cpp) (Book Validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Market Data"]
  node_lobster_messages["LOBSTER Messages"]
  node_message_parser["Message Parser<br/>[lobster_parser.cpp]"]
  node_typed_events["Typed Events"]
end

subgraph group_replay["Replay"]
  node_replay_engine["Replay Engine<br/>[replay_engine.cpp]"]
end

subgraph group_book["Matching Engine"]
  node_order_book["Order Book<br/>[order_book.cpp]"]
  node_book_side["Book Side<br/>[book_side.cpp]"]
  node_price_index["Price Index<br/>[price_index.cpp]"]
  node_price_level["Price Level<br/>[price_level.cpp]"]
  node_order["Order<br/>[order.cpp]"]
  node_trade["Trade Records<br/>[trade.hpp]"]
  node_strong_types["Strong Types<br/>[types.hpp]"]
end

subgraph group_validation["Validation"]
  node_reference_snapshots["LOBSTER Snapshots"]
  node_snapshot_parser["Snapshot Parser"]
  node_book_validator["Book Validator<br/>[book_validator.cpp]"]
  node_validation_cli["Validation CLI"]
end

subgraph group_measurement["Measurement"]
  node_latency_report["Latency Report<br/>[latency_report.cpp]"]
  node_latency_stats["Latency Statistics<br/>[latency_stats.cpp]"]
end

node_lobster_messages -->|"provides CSV"| node_message_parser
node_message_parser -->|"parses into"| node_typed_events
node_replay_engine -->|"reads events"| node_message_parser
node_replay_engine -->|"dispatches events"| node_order_book
node_order_book -->|"uses sides"| node_book_side
node_book_side -->|"indexes levels"| node_price_index
node_price_index -->|"owns levels"| node_price_level
node_price_level -->|"queues orders"| node_order
node_order_book -->|"returns trades"| node_trade
node_order -->|"uses typed values"| node_strong_types
node_order_book -->|"uses typed values"| node_strong_types
node_reference_snapshots -->|"provides snapshots"| node_snapshot_parser
node_validation_cli -->|"constructs"| node_replay_engine
node_validation_cli -->|"constructs"| node_order_book
node_validation_cli -->|"constructs"| node_snapshot_parser
node_validation_cli -->|"runs validation"| node_book_validator
node_book_validator -->|"advances replay"| node_replay_engine
node_book_validator -->|"compares snapshots"| node_snapshot_parser
node_book_validator -->|"checks book state"| node_order_book
node_latency_report -->|"measures replay"| node_replay_engine
node_latency_report -.->|"reports metrics"| node_latency_stats

click node_message_parser "https://github.com/zenithsoulx/mercury/blob/main/src/lobster_parser.cpp"
click node_typed_events "https://github.com/zenithsoulx/mercury/blob/main/include/replay/lobster_message.hpp"
click node_replay_engine "https://github.com/zenithsoulx/mercury/blob/main/src/replay_engine.cpp"
click node_order_book "https://github.com/zenithsoulx/mercury/blob/main/src/order_book.cpp"
click node_book_side "https://github.com/zenithsoulx/mercury/blob/main/src/book_side.cpp"
click node_price_index "https://github.com/zenithsoulx/mercury/blob/main/src/price_index.cpp"
click node_price_level "https://github.com/zenithsoulx/mercury/blob/main/src/price_level.cpp"
click node_order "https://github.com/zenithsoulx/mercury/blob/main/src/order.cpp"
click node_trade "https://github.com/zenithsoulx/mercury/blob/main/include/core/trade.hpp"
click node_strong_types "https://github.com/zenithsoulx/mercury/blob/main/include/core/types.hpp"
click node_snapshot_parser "https://github.com/zenithsoulx/mercury/blob/main/src/lobster_orderbook_parser.cpp"
click node_book_validator "https://github.com/zenithsoulx/mercury/blob/main/src/book_validator.cpp"
click node_validation_cli "https://github.com/zenithsoulx/mercury/blob/main/tools/validate_replay.cpp"
click node_latency_report "https://github.com/zenithsoulx/mercury/blob/main/tools/latency_report.cpp"
click node_latency_stats "https://github.com/zenithsoulx/mercury/blob/main/tools/latency_stats.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_lobster_messages,node_message_parser,node_typed_events toneBlue
class node_replay_engine toneAmber
class node_order_book,node_book_side,node_price_index,node_price_level,node_order,node_trade,node_strong_types toneMint
class node_reference_snapshots,node_snapshot_parser,node_book_validator,node_validation_cli toneRose
class node_latency_report,node_latency_stats toneIndigo
```

## Components

### Market Data

- **LOBSTER Messages**
- [Message Parser](https://github.com/zenithsoulx/mercury/blob/main/src/lobster_parser.cpp): `src/lobster_parser.cpp`
- [Typed Events](https://github.com/zenithsoulx/mercury/blob/main/include/replay/lobster_message.hpp): `include/replay/lobster_message.hpp`

### Replay

- [Replay Engine](https://github.com/zenithsoulx/mercury/blob/main/src/replay_engine.cpp): `src/replay_engine.cpp`

### Matching Engine

- [Order Book](https://github.com/zenithsoulx/mercury/blob/main/src/order_book.cpp): `src/order_book.cpp`
- [Book Side](https://github.com/zenithsoulx/mercury/blob/main/src/book_side.cpp): `src/book_side.cpp`
- [Price Index](https://github.com/zenithsoulx/mercury/blob/main/src/price_index.cpp): `src/price_index.cpp`
- [Price Level](https://github.com/zenithsoulx/mercury/blob/main/src/price_level.cpp): `src/price_level.cpp`
- [Order](https://github.com/zenithsoulx/mercury/blob/main/src/order.cpp): `src/order.cpp`
- [Trade Records](https://github.com/zenithsoulx/mercury/blob/main/include/core/trade.hpp): `include/core/trade.hpp`
- [Strong Types](https://github.com/zenithsoulx/mercury/blob/main/include/core/types.hpp): `include/core/types.hpp`

### Validation

- **LOBSTER Snapshots**
- [Snapshot Parser](https://github.com/zenithsoulx/mercury/blob/main/src/lobster_orderbook_parser.cpp): `src/lobster_orderbook_parser.cpp`
- [Book Validator](https://github.com/zenithsoulx/mercury/blob/main/src/book_validator.cpp): `src/book_validator.cpp`
- [Validation CLI](https://github.com/zenithsoulx/mercury/blob/main/tools/validate_replay.cpp): `tools/validate_replay.cpp`

### Measurement

- [Latency Report](https://github.com/zenithsoulx/mercury/blob/main/tools/latency_report.cpp): `tools/latency_report.cpp`
- [Latency Statistics](https://github.com/zenithsoulx/mercury/blob/main/tools/latency_stats.cpp): `tools/latency_stats.cpp`

## Connections

- LOBSTER Messages → Message Parser: provides CSV (evidence: `README.md`)
- Message Parser → Typed Events: parses into
- Replay Engine → Message Parser: reads events
- Replay Engine → Order Book: dispatches events (evidence: `README.md`)
- Order Book → Book Side: uses sides
- Book Side → Price Index: indexes levels
- Price Index → Price Level: owns levels
- Price Level → Order: queues orders
- Order Book → Trade Records: returns trades
- Order → Strong Types: uses typed values
- Order Book → Strong Types: uses typed values
- LOBSTER Snapshots → Snapshot Parser: provides snapshots (evidence: `README.md`)
- Validation CLI → Replay Engine: constructs (evidence: `tools/validate_replay.cpp`)
- Validation CLI → Order Book: constructs (evidence: `tools/validate_replay.cpp`)
- Validation CLI → Snapshot Parser: constructs (evidence: `tools/validate_replay.cpp`)
- Validation CLI → Book Validator: runs validation (evidence: `tools/validate_replay.cpp`)
- Book Validator → Replay Engine: advances replay
- Book Validator → Snapshot Parser: compares snapshots
- Book Validator → Order Book: checks book state
- Latency Report → Replay Engine: measures replay (evidence: `README.md`)
- Latency Report → Latency Statistics: reports metrics
