# saadsouilmi/queue-reactive architecture

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

- Interactive diagram: https://gitdiagram.com/saadsouilmi/queue-reactive
- Repository: https://github.com/saadsouilmi/queue-reactive

## Overview

Queue-Reactive is a data-driven limit-order-book simulation framework paired with a Python calibration pipeline. The main workflow preprocesses market data, estimates state-conditioned event and timing parameters, then runs C++ simulations that evolve an order book and save results. Additional documented capabilities include trading-strategy and metaorder simulations, market-impact calibration, and simulation analysis. The excerpts support the C++ runtime links and Python module dependency; wiring among unsampled scripts and other analysis tools is shown only where supported by names or README documentation.

Main entry points: [`cpp/src/simulation.cpp`](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/src/simulation.cpp) (Simulation engine), [`cpp/bin/run_metaorder.cpp`](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/run_metaorder.cpp) (Metaorder runner), [`cpp/bin`](https://github.com/saadsouilmi/queue-reactive/tree/main/cpp/bin) (Simulation runners), [`src/qr/estimations.py`](https://github.com/saadsouilmi/queue-reactive/blob/main/src/qr/estimations.py) (Parameter estimation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_est["Estimation"]
  node_preprocess["Data preprocessing<br/>[preprocessing.py]"]
  node_estimation["Parameter estimation<br/>[estimations.py]"]
  node_estimate_cli["QR parameter CLI"]
  node_daily_cli["Daily estimates CLI<br/>[daily_estimates.py]"]
end

subgraph group_sim["Simulation"]
  node_sim_cli["Simulation runners"]
  node_qr_model["QR event model<br/>[qr_model.h]"]
  node_book["Limit order book<br/>[orderbook.cpp]"]
  node_simulation["Simulation engine<br/>[simulation.cpp]"]
end

subgraph group_strategy["Trading Experiments"]
  node_strategy_api["Strategy trader<br/>[strategy.h]"]
  node_strategy_runner["Strategy runners"]
  node_hft_runner["HFT strategy runner"]
  node_metaorder["Metaorder runner<br/>[run_metaorder.cpp]"]
end

subgraph group_analysis["Calibration and Analysis"]
  node_impact["Impact calibration"]
  node_plot["Empirical comparison<br/>[plot_emp_vs_qr.py]"]
  node_analysis_utils["Estimation utilities<br/>[utils.py]"]
end

node_data[("Databento data")]
node_params["Estimated parameters"]
node_user(("Simulation user"))
node_results["Simulation results"]

node_data -->|"supplies data"| node_preprocess
node_preprocess -->|"prepares frames"| node_estimation
node_estimation -->|"imports helpers"| node_preprocess
node_estimate_cli -->|"estimates parameters"| node_estimation
node_daily_cli -->|"uses estimates"| node_estimation
node_estimate_cli -->|"writes parameters"| node_params
node_daily_cli -->|"writes estimates"| node_params
node_user -->|"starts run"| node_sim_cli
node_params -->|"loads parameters"| node_sim_cli
node_sim_cli -->|"configures model"| node_qr_model
node_sim_cli -->|"runs simulation"| node_simulation
node_simulation -->|"samples events"| node_qr_model
node_simulation -->|"applies orders"| node_book
node_simulation -->|"saves records"| node_results
node_user -->|"starts experiment"| node_strategy_runner
node_strategy_runner -->|"runs strategy loop"| node_simulation
node_strategy_runner -->|"uses trader"| node_strategy_api
node_user -->|"starts experiment"| node_hft_runner
node_hft_runner -->|"runs HFT loop"| node_simulation
node_user -->|"starts experiment"| node_metaorder
node_metaorder -->|"samples events"| node_qr_model
node_metaorder -->|"applies orders"| node_book
node_metaorder -->|"aggregates results"| node_results
node_user -->|"calibrates impact"| node_impact
node_results -.->|"compares outputs"| node_plot
node_results -.->|"analyzes results"| node_analysis_utils

click node_preprocess "https://github.com/saadsouilmi/queue-reactive/blob/main/src/qr/preprocessing.py"
click node_estimation "https://github.com/saadsouilmi/queue-reactive/blob/main/src/qr/estimations.py"
click node_estimate_cli "https://github.com/saadsouilmi/queue-reactive/blob/main/scripts/estimate_qr_params.py"
click node_daily_cli "https://github.com/saadsouilmi/queue-reactive/blob/main/scripts/daily_estimates.py"
click node_sim_cli "https://github.com/saadsouilmi/queue-reactive/tree/main/cpp/bin"
click node_qr_model "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/include/qr_model.h"
click node_book "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/src/orderbook.cpp"
click node_simulation "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/src/simulation.cpp"
click node_strategy_api "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/include/strategy.h"
click node_strategy_runner "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/sample_strategy.cpp"
click node_hft_runner "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/sample_hft_strategy.cpp"
click node_metaorder "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/run_metaorder.cpp"
click node_impact "https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/calibrate_impact.cpp"
click node_plot "https://github.com/saadsouilmi/queue-reactive/blob/main/scripts/plot_emp_vs_qr.py"
click node_analysis_utils "https://github.com/saadsouilmi/queue-reactive/blob/main/src/qr/utils.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_preprocess,node_estimation,node_estimate_cli,node_daily_cli,node_user toneBlue
class node_sim_cli,node_qr_model,node_book,node_simulation,node_data toneAmber
class node_strategy_api,node_strategy_runner,node_hft_runner,node_metaorder toneMint
class node_impact,node_plot,node_analysis_utils toneRose
class node_params,node_results toneIndigo
```

## Components

### Estimation

- [Data preprocessing](https://github.com/saadsouilmi/queue-reactive/blob/main/src/qr/preprocessing.py): `src/qr/preprocessing.py`
- [Parameter estimation](https://github.com/saadsouilmi/queue-reactive/blob/main/src/qr/estimations.py): `src/qr/estimations.py`
- [QR parameter CLI](https://github.com/saadsouilmi/queue-reactive/blob/main/scripts/estimate_qr_params.py): `scripts/estimate_qr_params.py`
- [Daily estimates CLI](https://github.com/saadsouilmi/queue-reactive/blob/main/scripts/daily_estimates.py): `scripts/daily_estimates.py`

### Simulation

- [Simulation runners](https://github.com/saadsouilmi/queue-reactive/tree/main/cpp/bin): `cpp/bin`
- [QR event model](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/include/qr_model.h): `cpp/include/qr_model.h`
- [Limit order book](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/src/orderbook.cpp): `cpp/src/orderbook.cpp`
- [Simulation engine](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/src/simulation.cpp): `cpp/src/simulation.cpp`

### Trading Experiments

- [Strategy trader](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/include/strategy.h): `cpp/include/strategy.h`
- [Strategy runners](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/sample_strategy.cpp): `cpp/bin/sample_strategy.cpp`
- [HFT strategy runner](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/sample_hft_strategy.cpp): `cpp/bin/sample_hft_strategy.cpp`
- [Metaorder runner](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/run_metaorder.cpp): `cpp/bin/run_metaorder.cpp`

### Calibration and Analysis

- [Impact calibration](https://github.com/saadsouilmi/queue-reactive/blob/main/cpp/bin/calibrate_impact.cpp): `cpp/bin/calibrate_impact.cpp`
- [Empirical comparison](https://github.com/saadsouilmi/queue-reactive/blob/main/scripts/plot_emp_vs_qr.py): `scripts/plot_emp_vs_qr.py`
- [Estimation utilities](https://github.com/saadsouilmi/queue-reactive/blob/main/src/qr/utils.py): `src/qr/utils.py`

### Other components

- **Databento data**
- **Estimated parameters**
- **Simulation user**
- **Simulation results**

## Connections

- Databento data → Data preprocessing: supplies data
- Data preprocessing → Parameter estimation: prepares frames
- Parameter estimation → Data preprocessing: imports helpers
- QR parameter CLI → Parameter estimation: estimates parameters
- Daily estimates CLI → Parameter estimation: uses estimates
- QR parameter CLI → Estimated parameters: writes parameters
- Daily estimates CLI → Estimated parameters: writes estimates
- Simulation user → Simulation runners: starts run
- Estimated parameters → Simulation runners: loads parameters
- Simulation runners → QR event model: configures model
- Simulation runners → Simulation engine: runs simulation
- Simulation engine → QR event model: samples events
- Simulation engine → Limit order book: applies orders
- Simulation engine → Simulation results: saves records
- Simulation user → Strategy runners: starts experiment
- Strategy runners → Simulation engine: runs strategy loop
- Strategy runners → Strategy trader: uses trader
- Simulation user → HFT strategy runner: starts experiment
- HFT strategy runner → Simulation engine: runs HFT loop
- Simulation user → Metaorder runner: starts experiment
- Metaorder runner → QR event model: samples events
- Metaorder runner → Limit order book: applies orders
- Metaorder runner → Simulation results: aggregates results
- Simulation user → Impact calibration: calibrates impact
- Simulation results → Empirical comparison: compares outputs
- Simulation results → Estimation utilities: analyzes results