# krrishapatel/exchange-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/krrishapatel/exchange-simulator
- Repository: https://github.com/krrishapatel/exchange-simulator

## Overview

Exchange Simulator is a simulated trading venue with a C++ matching core, Python agents and training tools, market-data workflows, FIX connectivity, and a live dashboard. The main workflow is agents or replayed order flow submitting orders through Python bindings to the matching engine, which produces fills and book state for simulation and learning. README capabilities guide several links to unsampled modules; those links are cited to the README rather than implying their source was inspected.

Main entry points: [`bindings/py_exchange.cpp`](https://github.com/krrishapatel/exchange-simulator/blob/main/bindings/py_exchange.cpp) (Python Bindings), [`rl/self_play_env.py`](https://github.com/krrishapatel/exchange-simulator/blob/main/rl/self_play_env.py) (Self-Play Environment), [`engine/src/matching_engine.cpp`](https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/matching_engine.cpp) (Matching Engine), [`gateway/fix_gateway.py`](https://github.com/krrishapatel/exchange-simulator/blob/main/gateway/fix_gateway.py) (FIX Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Exchange Core"]
  node_engine_types["Order Types<br/>[types.hpp]"]
  node_order_book["Order Book<br/>[order_book.cpp]"]
  node_matcher["Matching Engine"]
  node_multi_asset["Multi-Asset Engine"]
  node_bindings["Python Bindings<br/>[py_exchange.cpp]"]
end

subgraph group_trading["Agents and Simulation"]
  node_base_agent["Agent Interface<br/>[base.py]"]
  node_random_agent["Random Agent<br/>[random_agent.py]"]
  node_market_maker["Market Maker<br/>[market_maker.py]"]
  node_sim_loop["Simulation Loop<br/>[loop.py]"]
end

subgraph group_learning["Learning and Features"]
  node_trading_env["Trading Environment<br/>[trading_env.py]"]
  node_selfplay["Self-Play Environment<br/>[self_play_env.py]"]
  node_rl_training["RL Training<br/>[train_ppo.py]"]
  node_rl_evaluation["RL Evaluation<br/>[evaluate.py]"]
  node_tournaments["Tournaments and Elo<br/>[tournament.py]"]
  node_features["Feature Engine<br/>[engine.py]"]
  node_feature_dataset["Feature Dataset<br/>[dataset.py]"]
  node_feature_labels["Feature Labels<br/>[labels.py]"]
end

subgraph group_marketdata["Market Data"]
  node_hawkes["Hawkes Flow<br/>[hawkes.py]"]
  node_scenarios["Market Scenarios<br/>[scenarios.py]"]
  node_replay["LOBSTER Replay<br/>[replay.py]"]
  node_databento["Databento MBO<br/>[databento.py]"]
  node_backtest["Backtesting<br/>[backtest.py]"]
end

subgraph group_interfaces["External Interfaces"]
  node_fix_gateway["FIX Gateway<br/>[fix_gateway.py]"]
  node_fix_session["FIX Session<br/>[fix_session.py]"]
  node_fix_parser["FIX Parser<br/>[fix_parser.py]"]
  node_dashboard_server["Dashboard Server<br/>[app.py]"]
  node_dashboard_app["Dashboard App<br/>[App.jsx]"]
  node_dashboard_views["Dashboard Views"]
end

node_trader(("Trading Agent"))
node_fix_client(("FIX Client"))
node_browser(("Dashboard Browser"))

node_matcher -->|"updates book"| node_order_book
node_matcher -->|"uses orders"| node_engine_types
node_multi_asset -->|"routes symbols"| node_matcher
node_bindings -->|"exposes engine"| node_matcher
node_bindings -->|"exposes multi-asset"| node_multi_asset
node_trader -->|"submits orders"| node_bindings
node_random_agent -->|"implements"| node_base_agent
node_market_maker -->|"implements"| node_base_agent
node_sim_loop -->|"drives agents"| node_base_agent
node_sim_loop -->|"uses engine"| node_bindings
node_trading_env -->|"uses engine"| node_bindings
node_selfplay -->|"submits orders"| node_bindings
node_selfplay -->|"runs noise traders"| node_random_agent
node_rl_training -->|"trains policy"| node_trading_env
node_rl_training -->|"trains self-play"| node_selfplay
node_rl_evaluation -->|"evaluates policies"| node_selfplay
node_tournaments -->|"runs matches"| node_selfplay
node_tournaments -.->|"scores fills"| node_engine_types
node_feature_dataset -->|"computes features"| node_features
node_feature_dataset -->|"builds labels"| node_feature_labels
node_hawkes -.->|"configures flow"| node_scenarios
node_replay -->|"feeds backtest"| node_backtest
node_databento -.->|"feeds backtest"| node_backtest
node_backtest -->|"replays through"| node_bindings
node_fix_client -.->|"sends FIX"| node_fix_gateway
node_fix_gateway -->|"manages session"| node_fix_session
node_fix_session -->|"parses messages"| node_fix_parser
node_fix_gateway -.->|"routes orders"| node_bindings
node_browser -->|"streams ticks"| node_dashboard_server
node_dashboard_app -->|"receives ticks"| node_dashboard_server
node_dashboard_app -->|"renders views"| node_dashboard_views
node_dashboard_server -.->|"streams simulation"| node_sim_loop

click node_engine_types "https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/types.hpp"
click node_order_book "https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/order_book.cpp"
click node_matcher "https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/matching_engine.cpp"
click node_multi_asset "https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/multi_asset_engine.cpp"
click node_bindings "https://github.com/krrishapatel/exchange-simulator/blob/main/bindings/py_exchange.cpp"
click node_base_agent "https://github.com/krrishapatel/exchange-simulator/blob/main/agents/base.py"
click node_random_agent "https://github.com/krrishapatel/exchange-simulator/blob/main/agents/random_agent.py"
click node_market_maker "https://github.com/krrishapatel/exchange-simulator/blob/main/agents/market_maker.py"
click node_sim_loop "https://github.com/krrishapatel/exchange-simulator/blob/main/simulation/loop.py"
click node_trading_env "https://github.com/krrishapatel/exchange-simulator/blob/main/rl/trading_env.py"
click node_selfplay "https://github.com/krrishapatel/exchange-simulator/blob/main/rl/self_play_env.py"
click node_rl_training "https://github.com/krrishapatel/exchange-simulator/blob/main/rl/train_ppo.py"
click node_rl_evaluation "https://github.com/krrishapatel/exchange-simulator/blob/main/rl/evaluate.py"
click node_tournaments "https://github.com/krrishapatel/exchange-simulator/blob/main/rl/analysis/tournament.py"
click node_features "https://github.com/krrishapatel/exchange-simulator/blob/main/features/engine.py"
click node_feature_dataset "https://github.com/krrishapatel/exchange-simulator/blob/main/features/dataset.py"
click node_feature_labels "https://github.com/krrishapatel/exchange-simulator/blob/main/features/labels.py"
click node_hawkes "https://github.com/krrishapatel/exchange-simulator/blob/main/data/hawkes.py"
click node_scenarios "https://github.com/krrishapatel/exchange-simulator/blob/main/data/scenarios.py"
click node_replay "https://github.com/krrishapatel/exchange-simulator/blob/main/data/replay.py"
click node_databento "https://github.com/krrishapatel/exchange-simulator/blob/main/data/databento.py"
click node_backtest "https://github.com/krrishapatel/exchange-simulator/blob/main/data/backtest.py"
click node_fix_gateway "https://github.com/krrishapatel/exchange-simulator/blob/main/gateway/fix_gateway.py"
click node_fix_session "https://github.com/krrishapatel/exchange-simulator/blob/main/gateway/fix_session.py"
click node_fix_parser "https://github.com/krrishapatel/exchange-simulator/blob/main/gateway/fix_parser.py"
click node_dashboard_server "https://github.com/krrishapatel/exchange-simulator/blob/main/dashboard/server/app.py"
click node_dashboard_app "https://github.com/krrishapatel/exchange-simulator/blob/main/dashboard/frontend/src/App.jsx"
click node_dashboard_views "https://github.com/krrishapatel/exchange-simulator/tree/main/dashboard/frontend/src/components"

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_engine_types,node_order_book,node_matcher,node_multi_asset,node_bindings,node_fix_client,node_browser toneBlue
class node_base_agent,node_random_agent,node_market_maker,node_sim_loop toneAmber
class node_trading_env,node_selfplay,node_rl_training,node_rl_evaluation,node_tournaments,node_features,node_feature_dataset,node_feature_labels toneMint
class node_hawkes,node_scenarios,node_replay,node_databento,node_backtest toneRose
class node_fix_gateway,node_fix_session,node_fix_parser,node_dashboard_server,node_dashboard_app,node_dashboard_views,node_trader toneIndigo
```

## Components

### Exchange Core

- [Order Types](https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/types.hpp): `engine/src/types.hpp`
- [Order Book](https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/order_book.cpp): `engine/src/order_book.cpp`
- [Matching Engine](https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/matching_engine.cpp): `engine/src/matching_engine.cpp`
- [Multi-Asset Engine](https://github.com/krrishapatel/exchange-simulator/blob/main/engine/src/multi_asset_engine.cpp): `engine/src/multi_asset_engine.cpp`
- [Python Bindings](https://github.com/krrishapatel/exchange-simulator/blob/main/bindings/py_exchange.cpp): `bindings/py_exchange.cpp`

### Agents and Simulation

- [Agent Interface](https://github.com/krrishapatel/exchange-simulator/blob/main/agents/base.py): `agents/base.py`
- [Random Agent](https://github.com/krrishapatel/exchange-simulator/blob/main/agents/random_agent.py): `agents/random_agent.py`
- [Market Maker](https://github.com/krrishapatel/exchange-simulator/blob/main/agents/market_maker.py): `agents/market_maker.py`
- [Simulation Loop](https://github.com/krrishapatel/exchange-simulator/blob/main/simulation/loop.py): `simulation/loop.py`

### Learning and Features

- [Trading Environment](https://github.com/krrishapatel/exchange-simulator/blob/main/rl/trading_env.py): `rl/trading_env.py`
- [Self-Play Environment](https://github.com/krrishapatel/exchange-simulator/blob/main/rl/self_play_env.py): `rl/self_play_env.py`
- [RL Training](https://github.com/krrishapatel/exchange-simulator/blob/main/rl/train_ppo.py): `rl/train_ppo.py`
- [RL Evaluation](https://github.com/krrishapatel/exchange-simulator/blob/main/rl/evaluate.py): `rl/evaluate.py`
- [Tournaments and Elo](https://github.com/krrishapatel/exchange-simulator/blob/main/rl/analysis/tournament.py): `rl/analysis/tournament.py`
- [Feature Engine](https://github.com/krrishapatel/exchange-simulator/blob/main/features/engine.py): `features/engine.py`
- [Feature Dataset](https://github.com/krrishapatel/exchange-simulator/blob/main/features/dataset.py): `features/dataset.py`
- [Feature Labels](https://github.com/krrishapatel/exchange-simulator/blob/main/features/labels.py): `features/labels.py`

### Market Data

- [Hawkes Flow](https://github.com/krrishapatel/exchange-simulator/blob/main/data/hawkes.py): `data/hawkes.py`
- [Market Scenarios](https://github.com/krrishapatel/exchange-simulator/blob/main/data/scenarios.py): `data/scenarios.py`
- [LOBSTER Replay](https://github.com/krrishapatel/exchange-simulator/blob/main/data/replay.py): `data/replay.py`
- [Databento MBO](https://github.com/krrishapatel/exchange-simulator/blob/main/data/databento.py): `data/databento.py`
- [Backtesting](https://github.com/krrishapatel/exchange-simulator/blob/main/data/backtest.py): `data/backtest.py`

### External Interfaces

- [FIX Gateway](https://github.com/krrishapatel/exchange-simulator/blob/main/gateway/fix_gateway.py): `gateway/fix_gateway.py`
- [FIX Session](https://github.com/krrishapatel/exchange-simulator/blob/main/gateway/fix_session.py): `gateway/fix_session.py`
- [FIX Parser](https://github.com/krrishapatel/exchange-simulator/blob/main/gateway/fix_parser.py): `gateway/fix_parser.py`
- [Dashboard Server](https://github.com/krrishapatel/exchange-simulator/blob/main/dashboard/server/app.py): `dashboard/server/app.py`
- [Dashboard App](https://github.com/krrishapatel/exchange-simulator/blob/main/dashboard/frontend/src/App.jsx): `dashboard/frontend/src/App.jsx`
- [Dashboard Views](https://github.com/krrishapatel/exchange-simulator/tree/main/dashboard/frontend/src/components): `dashboard/frontend/src/components`

### Other components

- **Trading Agent**
- **FIX Client**
- **Dashboard Browser**

## Connections

- Matching Engine → Order Book: updates book (evidence: `engine/src/matching_engine.cpp`)
- Matching Engine → Order Types: uses orders
- Multi-Asset Engine → Matching Engine: routes symbols
- Python Bindings → Matching Engine: exposes engine (evidence: `bindings/py_exchange.cpp`)
- Python Bindings → Multi-Asset Engine: exposes multi-asset (evidence: `bindings/py_exchange.cpp`)
- Trading Agent → Python Bindings: submits orders
- Random Agent → Agent Interface: implements (evidence: `agents/random_agent.py`)
- Market Maker → Agent Interface: implements (evidence: `agents/market_maker.py`)
- Simulation Loop → Agent Interface: drives agents
- Simulation Loop → Python Bindings: uses engine
- Trading Environment → Python Bindings: uses engine
- Self-Play Environment → Python Bindings: submits orders (evidence: `rl/self_play_env.py`)
- Self-Play Environment → Random Agent: runs noise traders (evidence: `rl/self_play_env.py`)
- RL Training → Trading Environment: trains policy
- RL Training → Self-Play Environment: trains self-play
- RL Evaluation → Self-Play Environment: evaluates policies (evidence: `rl/evaluate.py`)
- Tournaments and Elo → Self-Play Environment: runs matches (evidence: `rl/analysis/tournament.py`)
- Tournaments and Elo → Order Types: scores fills
- Feature Dataset → Feature Engine: computes features (evidence: `features/dataset.py`)
- Feature Dataset → Feature Labels: builds labels (evidence: `features/dataset.py`)
- Hawkes Flow → Market Scenarios: configures flow
- LOBSTER Replay → Backtesting: feeds backtest
- Databento MBO → Backtesting: feeds backtest
- Backtesting → Python Bindings: replays through
- FIX Client → FIX Gateway: sends FIX
- FIX Gateway → FIX Session: manages session (evidence: `gateway/fix_gateway.py`)
- FIX Session → FIX Parser: parses messages (evidence: `gateway/fix_session.py`)
- FIX Gateway → Python Bindings: routes orders
- Dashboard Browser → Dashboard Server: streams ticks
- Dashboard App → Dashboard Server: receives ticks
- Dashboard App → Dashboard Views: renders views (evidence: `dashboard/frontend/src/App.jsx`)
- Dashboard Server → Simulation Loop: streams simulation
