# chrislernunes/hydrax. architecture

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

- Interactive diagram: https://gitdiagram.com/chrislernunes/hydrax.
- Repository: https://github.com/chrislernunes/hydrax.

## Overview

**1) Overall shape**
HydraExchange is a C++20 exchange-simulation codebase organized around a central matching core, with three main usage modes: offline simulation, benchmarking, and live market-data ingestion from Binance. The architecture is not a traditional service/app stack; it is a low-latency in-process system where most subsystems are compiled into the same executable via an include-based single-translation-unit pattern.

**2) Entry points and modes**
`main.cpp` is the CLI entry for the simulator/engine, while `examples/live_binance.cpp` builds the live feed demo. The README indicates runtime modes for example matching, execution-model experiments, agent simulation, and throughput benchmarking. These modes are thin wrappers over the same underlying engine and analytics components.

**3) Core trading engine**
The heart of the repo is `engine/matching_engine/` plus `engine/orderbook/`. Orders enter the matching engine, are stored in the limit order book, matched with price-time priority, and generate execution reports/trade events. The engine supports common order types such as limit, market, IOC, FOK, and post-only.

**4) Order lifecycle boundary**
`engine/gateway/order_gateway.cpp` and `engine/gateway/risk_checks.cpp` form the ingress boundary before orders reach the book. This is where validation/risk checks happen, separating “submit intent” from “engine acceptance.” The matching engine owns order allocation and lifecycle management, while the gateway constrains what is allowed to reach it.

**5) Limit order book internals**
`engine/orderbook/limit_order_book.cpp` and `price_level.cpp` implement the book data structure. The README describes a `std::map<Price, PriceLevel>` with intrusive linked-list queues, enabling fast best-price lookup and O(1)-style insertion/cancel behavior in the hot path. This is the primary stateful component of the exchange.

**6) Market data fanout**
`engine/market_data/feed_publisher.cpp` publishes book/trade updates from the engine to downstream consumers. This is the key outbound data path from matching events to analytics, simulations, or live dashboards. In architecture diagrams, this should sit beside the engine as the primary event dissemination layer.

**7) Shared domain model**
`include/hydra/types.hpp` and `include/hydra/order.hpp` define the core domain types: prices, quantities, order IDs, sides, and the order struct itself. These types are shared across engine, agents, simulation, analytics, and Binance integration, which makes them the main cross-cutting contract in the repo.

**8) Simulation and microstructure models**
The `simulation/` tree adds models that sit on top of the engine rather than replacing it. `latency_model/` simulates network, queueing, engine processing, and cancel-race effects; `execution_model/` simulates queue position, fill probability, and market impact; `replay/` generates synthetic order flow. These components feed the same matching engine but represent different research assumptions.

**9) Agent layer**
`agents/market_maker.cpp` contains strategy agents used in simulation. The README describes multiple strategy behaviors—market making, noise trading, momentum, and latency arbitrage—implemented as active participants that submit orders into the engine through the public API. In diagrams, agents should be shown as producers of order flow, not as part of the matching core.

**10) Analytics subsystem**
`analytics/orderflow_metrics.cpp` computes online metrics such as order-flow imbalance, Kyle’s lambda, spread, realized volatility, and alpha decay. These analytics consume market data/trade streams from the engine or live Binance feed and produce derived signals for dashboards and strategy evaluation. This subsystem is read-mostly and downstream of the trading/matching path.

**11) Live Binance integration**
The `binance/` directory is a separate live-data subsystem built around `ws_client.hpp` (TLS WebSocket client), `binance_stream.hpp` (stream parsing and local order-book reconstruction), and `live_analytics.hpp` (real-time metrics/dashboard). Data flow is Binance public WebSocket streams → local book reconstruction → analytics/output. OpenSSL is the only external runtime dependency, and the live path is distinct from the simulator path.

**12) Infrastructure and performance primitives**
`infrastructure/` provides low-level building blocks: lock-free queues, a ring buffer, a memory pool, and timestamp utilities. These are not business logic; they support the engine’s low-latency execution and avoid heap churn or locking on the hot path. They are fundamental to the system’s performance claims and should appear as shared infrastructure beneath the engine, simulation, and live-feed layers.

**13) Benchmarks and research artifacts**
`benchmarks/throughput_benchmark.cpp` measures engine and data-structure throughput. `HydraExchange_SSRN.pdf` and the README position the project as research-oriented microstructure infrastructure, so benchmarks are first-class artifacts rather than incidental tests. They validate the engine, memory pool, and order-book design.

**14) Practical architecture note**
Because many `.cpp` files are included directly rather than compiled as separate translation units, the repo behaves like a tightly composed codebase with explicit compile-time wiring. That means the architecture diagram should emphasize module boundaries and data flow, not process boundaries or distributed services.

Main entry points: [`engine/matching_engine/matching_engine.cpp`](https://github.com/chrislernunes/hydrax./blob/main/engine/matching_engine/matching_engine.cpp) (Matching core), [`infrastructure/memory_pool.hpp`](https://github.com/chrislernunes/hydrax./blob/main/infrastructure/memory_pool.hpp) (Infra primitives), [`engine/gateway/order_gateway.cpp`](https://github.com/chrislernunes/hydrax./blob/main/engine/gateway/order_gateway.cpp) (Order gateway), [`engine/orderbook/limit_order_book.cpp`](https://github.com/chrislernunes/hydrax./blob/main/engine/orderbook/limit_order_book.cpp) (Limit book)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_main_cpp["Main CLI<br/>entrypoint<br/>[main.cpp]"]
  node_live_demo["Live demo<br/>entrypoint<br/>[live_binance.cpp]"]
end

subgraph group_core["Core engine"]
  node_gateway["Order gateway<br/>ingress<br/>[order_gateway.cpp]"]
  node_risk_checks["Risk checks<br/>validation<br/>[risk_checks.cpp]"]
  node_matching_engine["Matching core"]
  node_trade_event["Trade event<br/>execution event<br/>[trade_event.cpp]"]
  node_order_book[("Limit book")]
  node_price_level["Price level<br/>book internals<br/>[price_level.cpp]"]
  node_publisher["Feed publisher<br/>fanout<br/>[feed_publisher.cpp]"]
end

subgraph group_models["Shared models"]
  node_order_api["Strategy API<br/>boundary<br/>[strategy_api.hpp]"]
  node_domain_types["Core types<br/>domain model<br/>[types.hpp]"]
  node_order_model["Order model<br/>domain model<br/>[order.hpp]"]
end

subgraph group_simulation["Simulation"]
  node_market_maker["Market maker<br/>agent<br/>[market_maker.cpp]"]
  node_latency_model["Latency model<br/>simulation model<br/>[network_delay.cpp]"]
  node_execution_model["Execution model<br/>simulation model<br/>[queue_position.cpp]"]
  node_synthetic_flow["Synthetic flow<br/>flow generator"]
end

subgraph group_live["Live feed"]
  node_binance_stream["Binance stream<br/>live ingestion<br/>[binance_stream.hpp]"]
  node_ws_client["WS client<br/>network client<br/>[ws_client.hpp]"]
  node_live_analytics["Live analytics<br/>live metrics<br/>[live_analytics.hpp]"]
end

subgraph group_support["Support"]
  node_analytics["Orderflow metrics<br/>analytics"]
  node_infra["Infra primitives<br/>support library<br/>[memory_pool.hpp]"]
  node_benchmark["Throughput bench<br/>benchmark"]
end

node_main_cpp -->|"submit orders"| node_gateway
node_main_cpp -->|"drive engine"| node_matching_engine
node_main_cpp -->|"measure flow"| node_analytics
node_live_demo -->|"connect"| node_ws_client
node_live_demo -->|"reconstruct"| node_binance_stream
node_gateway -->|"validate"| node_risk_checks
node_gateway -->|"forward"| node_matching_engine
node_order_api -->|"submit"| node_gateway
node_order_api -->|"used by"| node_market_maker
node_matching_engine -->|"mutate"| node_order_book
node_order_book -->|"manage levels"| node_price_level
node_matching_engine -->|"emit"| node_trade_event
node_matching_engine -->|"publish"| node_publisher
node_publisher -->|"feed"| node_analytics
node_publisher -->|"feed"| node_live_analytics
node_latency_model -->|"simulate"| node_matching_engine
node_execution_model -->|"estimate fills"| node_order_book
node_synthetic_flow -->|"generate inputs"| node_market_maker
node_market_maker -->|"submit orders"| node_order_api
node_binance_stream -->|"derive signals"| node_live_analytics
node_ws_client -->|"transport"| node_binance_stream
node_infra -->|"support"| node_matching_engine
node_infra -->|"support"| node_order_book
node_infra -->|"support"| node_binance_stream
node_benchmark -->|"measure"| node_matching_engine
node_benchmark -->|"measure"| node_infra

click node_main_cpp "https://github.com/chrislernunes/hydrax./blob/main/main.cpp"
click node_live_demo "https://github.com/chrislernunes/hydrax./blob/main/examples/live_binance.cpp"
click node_order_api "https://github.com/chrislernunes/hydrax./blob/main/api/strategy_api.hpp"
click node_domain_types "https://github.com/chrislernunes/hydrax./blob/main/include/hydra/types.hpp"
click node_order_model "https://github.com/chrislernunes/hydrax./blob/main/include/hydra/order.hpp"
click node_gateway "https://github.com/chrislernunes/hydrax./blob/main/engine/gateway/order_gateway.cpp"
click node_risk_checks "https://github.com/chrislernunes/hydrax./blob/main/engine/gateway/risk_checks.cpp"
click node_matching_engine "https://github.com/chrislernunes/hydrax./blob/main/engine/matching_engine/matching_engine.cpp"
click node_trade_event "https://github.com/chrislernunes/hydrax./blob/main/engine/matching_engine/trade_event.cpp"
click node_order_book "https://github.com/chrislernunes/hydrax./blob/main/engine/orderbook/limit_order_book.cpp"
click node_price_level "https://github.com/chrislernunes/hydrax./blob/main/engine/orderbook/price_level.cpp"
click node_publisher "https://github.com/chrislernunes/hydrax./blob/main/engine/market_data/feed_publisher.cpp"
click node_market_maker "https://github.com/chrislernunes/hydrax./blob/main/agents/market_maker.cpp"
click node_latency_model "https://github.com/chrislernunes/hydrax./blob/main/simulation/latency_model/network_delay.cpp"
click node_execution_model "https://github.com/chrislernunes/hydrax./blob/main/simulation/execution_model/queue_position.cpp"
click node_synthetic_flow "https://github.com/chrislernunes/hydrax./blob/main/simulation/replay/synthetic_orderflow.cpp"
click node_analytics "https://github.com/chrislernunes/hydrax./blob/main/analytics/orderflow_metrics.cpp"
click node_binance_stream "https://github.com/chrislernunes/hydrax./blob/main/binance/binance_stream.hpp"
click node_ws_client "https://github.com/chrislernunes/hydrax./blob/main/binance/ws_client.hpp"
click node_live_analytics "https://github.com/chrislernunes/hydrax./blob/main/binance/live_analytics.hpp"
click node_infra "https://github.com/chrislernunes/hydrax./blob/main/infrastructure/memory_pool.hpp"
click node_benchmark "https://github.com/chrislernunes/hydrax./blob/main/benchmarks/throughput_benchmark.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_live_demo toneBlue
class node_gateway,node_risk_checks,node_matching_engine,node_trade_event,node_order_book,node_price_level,node_publisher toneAmber
class node_order_api,node_domain_types,node_order_model toneMint
class node_market_maker,node_latency_model,node_execution_model,node_synthetic_flow toneRose
class node_binance_stream,node_ws_client,node_live_analytics toneIndigo
class node_analytics,node_infra,node_benchmark toneTeal
```

## Components

### Entry points

CLI and demo executables that wire the same core modules into different runtime modes.

- [Main CLI](https://github.com/chrislernunes/hydrax./blob/main/main.cpp): entrypoint · Primary simulator and engine entry point. · `main.cpp`
- [Live demo](https://github.com/chrislernunes/hydrax./blob/main/examples/live_binance.cpp): entrypoint · Executable example for Binance market-data ingestion. · `examples/live_binance.cpp`

### Core engine

Matching, order book, gateway, and market-data emission.

- [Order gateway](https://github.com/chrislernunes/hydrax./blob/main/engine/gateway/order_gateway.cpp): ingress · Validates and forwards order intent into the engine. · `engine/gateway/order_gateway.cpp`
- [Risk checks](https://github.com/chrislernunes/hydrax./blob/main/engine/gateway/risk_checks.cpp): validation · Pre-engine checks and acceptance constraints. · `engine/gateway/risk_checks.cpp`
- [Matching core](https://github.com/chrislernunes/hydrax./blob/main/engine/matching_engine/matching_engine.cpp): matching · Price-time matching, order lifecycle, and execution handling. · `engine/matching_engine/matching_engine.cpp`
- [Trade event](https://github.com/chrislernunes/hydrax./blob/main/engine/matching_engine/trade_event.cpp): execution event · Trade and execution-report representation emitted by the engine. · `engine/matching_engine/trade_event.cpp`
- [Limit book](https://github.com/chrislernunes/hydrax./blob/main/engine/orderbook/limit_order_book.cpp): book · Primary stateful order book structure and best-price management. · `engine/orderbook/limit_order_book.cpp`
- [Price level](https://github.com/chrislernunes/hydrax./blob/main/engine/orderbook/price_level.cpp): book internals · Per-price queue and level bookkeeping for the book hot path. · `engine/orderbook/price_level.cpp`
- [Feed publisher](https://github.com/chrislernunes/hydrax./blob/main/engine/market_data/feed_publisher.cpp): fanout · Broadcasts book and trade updates to downstream consumers. · `engine/market_data/feed_publisher.cpp`

### Shared models

Domain contracts used across engine, simulation, analytics, and live feeds.

- [Strategy API](https://github.com/chrislernunes/hydrax./blob/main/api/strategy_api.hpp): boundary · Public submission surface used by agents and simulations. · `api/strategy_api.hpp`
- [Core types](https://github.com/chrislernunes/hydrax./blob/main/include/hydra/types.hpp): domain model · Prices, quantities, sides, IDs, and shared order contracts. · `include/hydra/types.hpp`
- [Order model](https://github.com/chrislernunes/hydrax./blob/main/include/hydra/order.hpp): domain model · Order structure and lifecycle-facing order fields. · `include/hydra/order.hpp`

### Simulation

Research models that generate flow, latency, and execution assumptions.

- [Market maker](https://github.com/chrislernunes/hydrax./blob/main/agents/market_maker.cpp): agent · Representative strategy agent that submits orders into the engine. · `agents/market_maker.cpp`
- [Latency model](https://github.com/chrislernunes/hydrax./blob/main/simulation/latency_model/network_delay.cpp): simulation model · Network, queueing, processing, and cancel-race delay simulation. · `simulation/latency_model/network_delay.cpp`
- [Execution model](https://github.com/chrislernunes/hydrax./blob/main/simulation/execution_model/queue_position.cpp): simulation model · Queue position, fill probability, and market-impact assumptions. · `simulation/execution_model/queue_position.cpp`
- [Synthetic flow](https://github.com/chrislernunes/hydrax./blob/main/simulation/replay/synthetic_orderflow.cpp): flow generator · Synthetic order-flow generation for replay and experiments. · `simulation/replay/synthetic_orderflow.cpp`

### Live feed

Binance ingestion and local reconstruction path.

- [Binance stream](https://github.com/chrislernunes/hydrax./blob/main/binance/binance_stream.hpp): live ingestion · WebSocket stream parsing and local book reconstruction. · `binance/binance_stream.hpp`
- [WS client](https://github.com/chrislernunes/hydrax./blob/main/binance/ws_client.hpp): network client · TLS WebSocket transport used by the live Binance path. · `binance/ws_client.hpp`
- [Live analytics](https://github.com/chrislernunes/hydrax./blob/main/binance/live_analytics.hpp): live metrics · Real-time metrics and dashboard logic for live market data. · `binance/live_analytics.hpp`

### Support

Infrastructure and measurement utilities.

- [Orderflow metrics](https://github.com/chrislernunes/hydrax./blob/main/analytics/orderflow_metrics.cpp): analytics · Online market-quality and alpha-style metrics from feeds. · `analytics/orderflow_metrics.cpp`
- [Infra primitives](https://github.com/chrislernunes/hydrax./blob/main/infrastructure/memory_pool.hpp): support library · Lock-free queues, ring buffer, memory pool, and timestamp utilities. · `infrastructure/memory_pool.hpp`
- [Throughput bench](https://github.com/chrislernunes/hydrax./blob/main/benchmarks/throughput_benchmark.cpp): benchmark · Measures engine and data-structure throughput. · `benchmarks/throughput_benchmark.cpp`

## Connections

- Main CLI → Order gateway: submit orders · CLI-driven modes exercise the order ingress path.
- Main CLI → Matching core: drive engine · Runs the central exchange simulation and matching loop.
- Main CLI → Orderflow metrics: measure flow · Offline modes consume engine output for analysis.
- Live demo → WS client: connect · Live demo opens the Binance transport.
- Live demo → Binance stream: reconstruct · Parses public streams into local book state.
- Order gateway → Risk checks: validate · Orders are checked before acceptance.
- Order gateway → Matching core: forward · Accepted orders enter the matching core.
- Strategy API → Order gateway: submit · Strategies and simulations use the public API boundary.
- Strategy API → Market maker: used by · Strategy agents submit through the same interface.
- Matching core → Limit book: mutate · Matching updates the limit order book state.
- Limit book → Price level: manage levels · Price levels implement the book’s queue structure.
- Matching core → Trade event: emit · Matches generate execution and trade events.
- Matching core → Feed publisher: publish · Book and trade updates fan out to consumers.
- Feed publisher → Orderflow metrics: feed · Analytics consume book and trade streams.
- Feed publisher → Live analytics: feed · Live metrics subscribe to the same outbound stream.
- Latency model → Matching core: simulate · Latency effects are applied against engine interaction.
- Execution model → Limit book: estimate fills · Execution assumptions depend on queue position and book state.
- Synthetic flow → Market maker: generate inputs · Synthetic replay and flow models drive agents.
- Market maker → Strategy API: submit orders · Agent orders enter through the shared boundary.
- Binance stream → Live analytics: derive signals · Reconstructed live data feeds downstream metrics.
- WS client → Binance stream: transport · WebSocket transport carries Binance public data.
- Infra primitives → Matching core: support · Low-latency primitives back hot-path execution.
- Infra primitives → Limit book: support · Book operations rely on shared memory and queue primitives.
- Infra primitives → Binance stream: support · Live ingestion uses common buffering and timing utilities.
- Throughput bench → Matching core: measure · Benchmarks exercise the engine core.
- Throughput bench → Infra primitives: measure · Throughput tests also cover infrastructure primitives.
