# nkaz001/hftbacktest architecture

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

- Interactive diagram: https://gitdiagram.com/nkaz001/hftbacktest
- Repository: https://github.com/nkaz001/hftbacktest

## Overview

HftBacktest is a market-replay backtesting framework for HFT and market-making strategies, with a Rust live-trading path and Python/Numba interface. The principal workflow is to prepare market data, configure assets and simulation models, run a strategy against reconstructed books, and inspect results; live deployment reuses strategy logic through exchange connectors. The graph preserves the collector and exchange integration branches as well as the documented backtest capabilities. Some subsystem paths are directories because their implementation files were not sampled; unsampled call relationships are omitted.

Main entry points: [`hftbacktest/src/backtest/mod.rs`](https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/mod.rs) (Backtest Runtime), [`connector/src/main.rs`](https://github.com/nkaz001/hftbacktest/blob/master/connector/src/main.rs) (Connector Runtime), [`collector/src`](https://github.com/nkaz001/hftbacktest/tree/master/collector/src) (Exchange Feeds), [`py-hftbacktest/hftbacktest/__init__.py`](https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/hftbacktest/__init__.py) (Python API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market Data"]
  node_collector_cli["Data Collector<br/>[main.rs]"]
  node_exchange_collectors["Exchange Feeds"]
  node_collector_throttle["Request Throttling<br/>[throttler.rs]"]
  node_data_writer["Data Writer<br/>[file.rs]"]
  node_data_prep["Data Utilities"]
  node_data_validation["Data Validation<br/>[validation.py]"]
end

subgraph group_simulation["Backtest Engine"]
  node_data_reader["Replay Data Reader<br/>[reader.rs]"]
  node_backtest_engine["Backtest Runtime<br/>[mod.rs]"]
  node_book_depth["Market Depth"]
  node_fill_models["Queue Fill Models<br/>[queue.rs]"]
  node_exchange_process["Exchange Fill Process"]
end

subgraph group_python["Python Interface"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_native_binding["Native Backtest Binding<br/>[lib.rs]"]
  node_python_stats["Performance Statistics<br/>[stats.py]"]
end

subgraph group_live["Live Trading"]
  node_live_bot["Live Bot Runtime<br/>[bot.rs]"]
  node_live_ipc["Live IPC"]
end

subgraph group_connectors["Exchange Connectors"]
  node_connector_runtime["Connector Runtime<br/>[main.rs]"]
  node_binance_futures["Binance Futures"]
  node_binance_spot["Binance Spot"]
  node_bybit["Bybit"]
end

node_researcher(("Strategy Developer"))

node_researcher -->|"collects feeds"| node_collector_cli
node_collector_cli -->|"dispatches exchange"| node_exchange_collectors
node_exchange_collectors -->|"throttles snapshots"| node_collector_throttle
node_exchange_collectors -->|"sends records"| node_data_writer
node_researcher -->|"prepares data"| node_data_prep
node_data_prep -.->|"validates data"| node_data_validation
node_data_validation -.->|"supplies replay data"| node_data_reader
node_researcher -->|"configures strategy"| node_python_api
node_python_api -->|"calls native runtime"| node_native_binding
node_native_binding -->|"builds backtest"| node_backtest_engine
node_backtest_engine -->|"reads replay data"| node_data_reader
node_backtest_engine -->|"updates market depth"| node_book_depth
node_backtest_engine -->|"uses queue model"| node_fill_models
node_backtest_engine -->|"simulates fills"| node_exchange_process
node_python_api -.->|"analyzes results"| node_python_stats
node_researcher -->|"deploys strategy"| node_live_bot
node_live_bot -.->|"communicates through"| node_live_ipc
node_live_bot -.->|"routes live orders"| node_connector_runtime
node_connector_runtime -->|"selects exchange"| node_binance_futures
node_connector_runtime -->|"selects exchange"| node_binance_spot
node_connector_runtime -->|"selects exchange"| node_bybit

click node_collector_cli "https://github.com/nkaz001/hftbacktest/blob/master/collector/src/main.rs"
click node_exchange_collectors "https://github.com/nkaz001/hftbacktest/tree/master/collector/src"
click node_collector_throttle "https://github.com/nkaz001/hftbacktest/blob/master/collector/src/throttler.rs"
click node_data_writer "https://github.com/nkaz001/hftbacktest/blob/master/collector/src/file.rs"
click node_data_prep "https://github.com/nkaz001/hftbacktest/tree/master/py-hftbacktest/hftbacktest/data/utils"
click node_data_validation "https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/hftbacktest/data/validation.py"
click node_data_reader "https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/data/reader.rs"
click node_backtest_engine "https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/mod.rs"
click node_book_depth "https://github.com/nkaz001/hftbacktest/tree/master/hftbacktest/src/depth"
click node_fill_models "https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/models/queue.rs"
click node_exchange_process "https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/proc/partialfillexchange.rs"
click node_python_api "https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/hftbacktest/__init__.py"
click node_native_binding "https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/src/lib.rs"
click node_python_stats "https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/hftbacktest/stats/stats.py"
click node_live_bot "https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/live/bot.rs"
click node_live_ipc "https://github.com/nkaz001/hftbacktest/tree/master/hftbacktest/src/live/ipc"
click node_connector_runtime "https://github.com/nkaz001/hftbacktest/blob/master/connector/src/main.rs"
click node_binance_futures "https://github.com/nkaz001/hftbacktest/tree/master/connector/src/binancefutures"
click node_binance_spot "https://github.com/nkaz001/hftbacktest/tree/master/connector/src/binancespot"
click node_bybit "https://github.com/nkaz001/hftbacktest/tree/master/connector/src/bybit"

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_collector_cli,node_exchange_collectors,node_collector_throttle,node_data_writer,node_data_prep,node_data_validation toneBlue
class node_data_reader,node_backtest_engine,node_book_depth,node_fill_models,node_exchange_process toneAmber
class node_python_api,node_native_binding,node_python_stats toneMint
class node_live_bot,node_live_ipc toneRose
class node_connector_runtime,node_binance_futures,node_binance_spot,node_bybit,node_researcher toneIndigo
```

## Components

### Market Data

- [Data Collector](https://github.com/nkaz001/hftbacktest/blob/master/collector/src/main.rs): `collector/src/main.rs`
- [Exchange Feeds](https://github.com/nkaz001/hftbacktest/tree/master/collector/src): `collector/src`
- [Request Throttling](https://github.com/nkaz001/hftbacktest/blob/master/collector/src/throttler.rs): `collector/src/throttler.rs`
- [Data Writer](https://github.com/nkaz001/hftbacktest/blob/master/collector/src/file.rs): `collector/src/file.rs`
- [Data Utilities](https://github.com/nkaz001/hftbacktest/tree/master/py-hftbacktest/hftbacktest/data/utils): `py-hftbacktest/hftbacktest/data/utils`
- [Data Validation](https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/hftbacktest/data/validation.py): `py-hftbacktest/hftbacktest/data/validation.py`

### Backtest Engine

- [Replay Data Reader](https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/data/reader.rs): `hftbacktest/src/backtest/data/reader.rs`
- [Backtest Runtime](https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/mod.rs): `hftbacktest/src/backtest/mod.rs`
- [Market Depth](https://github.com/nkaz001/hftbacktest/tree/master/hftbacktest/src/depth): `hftbacktest/src/depth`
- [Queue Fill Models](https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/models/queue.rs): `hftbacktest/src/backtest/models/queue.rs`
- [Exchange Fill Process](https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/backtest/proc/partialfillexchange.rs): `hftbacktest/src/backtest/proc/partialfillexchange.rs`

### Python Interface

- [Python API](https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/hftbacktest/__init__.py): `py-hftbacktest/hftbacktest/__init__.py`
- [Native Backtest Binding](https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/src/lib.rs): `py-hftbacktest/src/lib.rs`
- [Performance Statistics](https://github.com/nkaz001/hftbacktest/blob/master/py-hftbacktest/hftbacktest/stats/stats.py): `py-hftbacktest/hftbacktest/stats/stats.py`

### Live Trading

- [Live Bot Runtime](https://github.com/nkaz001/hftbacktest/blob/master/hftbacktest/src/live/bot.rs): `hftbacktest/src/live/bot.rs`
- [Live IPC](https://github.com/nkaz001/hftbacktest/tree/master/hftbacktest/src/live/ipc): `hftbacktest/src/live/ipc`

### Exchange Connectors

- [Connector Runtime](https://github.com/nkaz001/hftbacktest/blob/master/connector/src/main.rs): `connector/src/main.rs`
- [Binance Futures](https://github.com/nkaz001/hftbacktest/tree/master/connector/src/binancefutures): `connector/src/binancefutures`
- [Binance Spot](https://github.com/nkaz001/hftbacktest/tree/master/connector/src/binancespot): `connector/src/binancespot`
- [Bybit](https://github.com/nkaz001/hftbacktest/tree/master/connector/src/bybit): `connector/src/bybit`

### Other components

- **Strategy Developer**

## Connections

- Strategy Developer → Data Collector: collects feeds (evidence: `collector/src/main.rs`)
- Data Collector → Exchange Feeds: dispatches exchange (evidence: `collector/src/main.rs`)
- Exchange Feeds → Request Throttling: throttles snapshots (evidence: `collector/src/binance/mod.rs`)
- Exchange Feeds → Data Writer: sends records (evidence: `collector/src/binance/mod.rs`)
- Strategy Developer → Data Utilities: prepares data
- Data Utilities → Data Validation: validates data (evidence: `py-hftbacktest/hftbacktest/data/utils/tardis.py`)
- Data Validation → Replay Data Reader: supplies replay data
- Strategy Developer → Python API: configures strategy
- Python API → Native Backtest Binding: calls native runtime
- Native Backtest Binding → Backtest Runtime: builds backtest (evidence: `py-hftbacktest/src/lib.rs`)
- Backtest Runtime → Replay Data Reader: reads replay data (evidence: `hftbacktest/src/backtest/mod.rs`)
- Backtest Runtime → Market Depth: updates market depth (evidence: `hftbacktest/src/lib.rs`)
- Backtest Runtime → Queue Fill Models: uses queue model (evidence: `hftbacktest/src/backtest/mod.rs`)
- Backtest Runtime → Exchange Fill Process: simulates fills (evidence: `hftbacktest/src/backtest/mod.rs`)
- Python API → Performance Statistics: analyzes results
- Strategy Developer → Live Bot Runtime: deploys strategy
- Live Bot Runtime → Live IPC: communicates through
- Live Bot Runtime → Connector Runtime: routes live orders
- Connector Runtime → Binance Futures: selects exchange (evidence: `connector/src/main.rs`)
- Connector Runtime → Binance Spot: selects exchange (evidence: `connector/src/main.rs`)
- Connector Runtime → Bybit: selects exchange (evidence: `connector/src/main.rs`)
