# sjain7117/quant-backtest-engine architecture

> Architecture diagram of the GitHub repository sjain7117/quant-backtest-engine, 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/sjain7117/quant-backtest-engine
- Repository: https://github.com/sjain7117/quant-backtest-engine

## Overview

This repository is a quantitative strategy research project built around an event-driven backtesting engine. Its main workflow loads adjusted prices, lets pairs or momentum strategies produce signals using cursor-limited history, executes orders on the next bar with modeled costs, accounts for fills and equity, then reports performance. Separate research branches screen cointegration and sizing, and explore market regimes with feature construction, detectors, and a strategy overlay. Engine wiring and regime components not directly excerpted are represented only where the README or source index supports their relationships.

Main entry points: [`engine/backtest.py`](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/backtest.py) (Event Loop), [`engine/events.py`](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/events.py) (Event Messages), [`data/loader.py`](https://github.com/sjain7117/quant-backtest-engine/blob/main/data/loader.py) (Price Loader), [`regime/features.py`](https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/features.py) (Regime Features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market Data"]
  node_loader["Price Loader<br/>[loader.py]"]
end

subgraph group_engine["Backtest Engine"]
  node_pair_data["Pair Data Handler<br/>[data_handler.py]"]
  node_multi_data["Multi-Asset Handler<br/>[data_handler.py]"]
  node_events["Event Messages<br/>[events.py]"]
  node_backtest["Event Loop<br/>[backtest.py]"]
  node_strategy_base["Strategy Interface<br/>[strategy.py]"]
  node_execution["Simulated Execution<br/>[execution.py]"]
  node_portfolio["Portfolio Accounting<br/>[portfolio.py]"]
end

subgraph group_strategies["Trading Strategies"]
  node_pairs["Pairs Strategy<br/>[pairs_trading.py]"]
  node_momentum["Momentum Strategy<br/>[momentum.py]"]
  node_other_strategies["Baseline Strategies"]
end

subgraph group_research["Quant Research"]
  node_cointegration["Pair Screening<br/>[cointegration.py]"]
  node_kelly["Kelly Sizing<br/>[kelly.py]"]
  node_performance["Performance Metrics<br/>[performance.py]"]
end

subgraph group_regime["Regime Analysis"]
  node_features["Regime Features<br/>[features.py]"]
  node_hmm["HMM Detector<br/>[detector_hmm.py]"]
  node_online["Online Detector<br/>[detector_online.py]"]
  node_rule["Rule Detector<br/>[detector_rule.py]"]
  node_sleeves["Strategy Sleeves<br/>[sleeves.py]"]
  node_overlay["Regime Overlay<br/>[overlay.py]"]
end

node_researcher(("Researcher"))
node_price_source(("Market Data Source"))

node_researcher -->|"runs"| node_backtest
node_price_source -->|"provides prices"| node_loader
node_loader -->|"loads pairs"| node_pair_data
node_loader -->|"loads universe"| node_multi_data
node_pair_data -->|"emits bars"| node_events
node_multi_data -->|"emits bars"| node_events
node_backtest -.->|"advances bars"| node_pair_data
node_backtest -->|"dispatches"| node_events
node_backtest -->|"executes pending"| node_execution
node_backtest -.->|"requests signals"| node_strategy_base
node_backtest -->|"routes events"| node_portfolio
node_pairs -->|"implements"| node_strategy_base
node_momentum -->|"implements"| node_strategy_base
node_other_strategies -->|"implements"| node_strategy_base
node_pairs -->|"emits signals"| node_events
node_momentum -->|"emits signals"| node_events
node_portfolio -->|"creates orders"| node_events
node_execution -->|"creates fills"| node_events
node_backtest -.->|"reports curve"| node_performance
node_researcher -->|"screens pairs"| node_cointegration
node_cointegration -.->|"analyzes prices"| node_loader
node_researcher -->|"sizes positions"| node_kelly
node_researcher -->|"studies regimes"| node_features
node_features -->|"loads market data"| node_loader
node_hmm -->|"builds inputs"| node_features
node_online -->|"uses features"| node_features
node_rule -->|"uses features"| node_features
node_sleeves -->|"runs strategy"| node_pairs
node_sleeves -->|"runs strategy"| node_momentum
node_overlay -->|"uses detector"| node_online
node_overlay -->|"combines sleeves"| node_sleeves
node_overlay -->|"evaluates results"| node_performance

click node_loader "https://github.com/sjain7117/quant-backtest-engine/blob/main/data/loader.py"
click node_pair_data "https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/data_handler.py"
click node_multi_data "https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/data_handler.py"
click node_events "https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/events.py"
click node_backtest "https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/backtest.py"
click node_strategy_base "https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/strategy.py"
click node_execution "https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/execution.py"
click node_portfolio "https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/portfolio.py"
click node_pairs "https://github.com/sjain7117/quant-backtest-engine/blob/main/strategies/pairs_trading.py"
click node_momentum "https://github.com/sjain7117/quant-backtest-engine/blob/main/strategies/momentum.py"
click node_other_strategies "https://github.com/sjain7117/quant-backtest-engine/tree/main/strategies"
click node_cointegration "https://github.com/sjain7117/quant-backtest-engine/blob/main/analysis/cointegration.py"
click node_kelly "https://github.com/sjain7117/quant-backtest-engine/blob/main/analysis/kelly.py"
click node_performance "https://github.com/sjain7117/quant-backtest-engine/blob/main/analysis/performance.py"
click node_features "https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/features.py"
click node_hmm "https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/detector_hmm.py"
click node_online "https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/detector_online.py"
click node_rule "https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/detector_rule.py"
click node_sleeves "https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/sleeves.py"
click node_overlay "https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/overlay.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_loader toneBlue
class node_pair_data,node_multi_data,node_events,node_backtest,node_strategy_base,node_execution,node_portfolio toneAmber
class node_pairs,node_momentum,node_other_strategies toneMint
class node_cointegration,node_kelly,node_performance toneRose
class node_features,node_hmm,node_online,node_rule,node_sleeves,node_overlay,node_researcher,node_price_source toneIndigo
```

## Components

### Market Data

- [Price Loader](https://github.com/sjain7117/quant-backtest-engine/blob/main/data/loader.py): `data/loader.py`

### Backtest Engine

- [Pair Data Handler](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/data_handler.py): `engine/data_handler.py`
- [Multi-Asset Handler](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/data_handler.py): `engine/data_handler.py`
- [Event Messages](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/events.py): `engine/events.py`
- [Event Loop](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/backtest.py): `engine/backtest.py`
- [Strategy Interface](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/strategy.py): `engine/strategy.py`
- [Simulated Execution](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/execution.py): `engine/execution.py`
- [Portfolio Accounting](https://github.com/sjain7117/quant-backtest-engine/blob/main/engine/portfolio.py): `engine/portfolio.py`

### Trading Strategies

- [Pairs Strategy](https://github.com/sjain7117/quant-backtest-engine/blob/main/strategies/pairs_trading.py): `strategies/pairs_trading.py`
- [Momentum Strategy](https://github.com/sjain7117/quant-backtest-engine/blob/main/strategies/momentum.py): `strategies/momentum.py`
- [Baseline Strategies](https://github.com/sjain7117/quant-backtest-engine/tree/main/strategies): `strategies`

### Quant Research

- [Pair Screening](https://github.com/sjain7117/quant-backtest-engine/blob/main/analysis/cointegration.py): `analysis/cointegration.py`
- [Kelly Sizing](https://github.com/sjain7117/quant-backtest-engine/blob/main/analysis/kelly.py): `analysis/kelly.py`
- [Performance Metrics](https://github.com/sjain7117/quant-backtest-engine/blob/main/analysis/performance.py): `analysis/performance.py`

### Regime Analysis

- [Regime Features](https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/features.py): `regime/features.py`
- [HMM Detector](https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/detector_hmm.py): `regime/detector_hmm.py`
- [Online Detector](https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/detector_online.py): `regime/detector_online.py`
- [Rule Detector](https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/detector_rule.py): `regime/detector_rule.py`
- [Strategy Sleeves](https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/sleeves.py): `regime/sleeves.py`
- [Regime Overlay](https://github.com/sjain7117/quant-backtest-engine/blob/main/regime/overlay.py): `regime/overlay.py`

### Other components

- **Researcher**
- **Market Data Source**

## Connections

- Researcher → Event Loop: runs (evidence: `README.md`)
- Market Data Source → Price Loader: provides prices (evidence: `data/loader.py`)
- Price Loader → Pair Data Handler: loads pairs (evidence: `engine/data_handler.py`)
- Price Loader → Multi-Asset Handler: loads universe (evidence: `engine/data_handler.py`)
- Pair Data Handler → Event Messages: emits bars (evidence: `engine/data_handler.py`)
- Multi-Asset Handler → Event Messages: emits bars (evidence: `engine/data_handler.py`)
- Event Loop → Pair Data Handler: advances bars
- Event Loop → Event Messages: dispatches (evidence: `engine/backtest.py`)
- Event Loop → Simulated Execution: executes pending (evidence: `engine/backtest.py`)
- Event Loop → Strategy Interface: requests signals
- Event Loop → Portfolio Accounting: routes events (evidence: `engine/backtest.py`)
- Pairs Strategy → Strategy Interface: implements (evidence: `strategies/pairs_trading.py`)
- Momentum Strategy → Strategy Interface: implements (evidence: `strategies/momentum.py`)
- Baseline Strategies → Strategy Interface: implements (evidence: `strategies/buy_and_hold.py`)
- Pairs Strategy → Event Messages: emits signals (evidence: `strategies/pairs_trading.py`)
- Momentum Strategy → Event Messages: emits signals (evidence: `strategies/momentum.py`)
- Portfolio Accounting → Event Messages: creates orders (evidence: `engine/portfolio.py`)
- Simulated Execution → Event Messages: creates fills (evidence: `engine/execution.py`)
- Event Loop → Performance Metrics: reports curve
- Researcher → Pair Screening: screens pairs (evidence: `README.md`)
- Pair Screening → Price Loader: analyzes prices
- Researcher → Kelly Sizing: sizes positions (evidence: `README.md`)
- Researcher → Regime Features: studies regimes (evidence: `README.md`)
- Regime Features → Price Loader: loads market data (evidence: `regime/features.py`)
- HMM Detector → Regime Features: builds inputs (evidence: `regime/detector_hmm.py`)
- Online Detector → Regime Features: uses features (evidence: `regime/detector_online.py`)
- Rule Detector → Regime Features: uses features (evidence: `regime/detector_rule.py`)
- Strategy Sleeves → Pairs Strategy: runs strategy (evidence: `regime/sleeves.py`)
- Strategy Sleeves → Momentum Strategy: runs strategy (evidence: `regime/sleeves.py`)
- Regime Overlay → Online Detector: uses detector (evidence: `scripts/regime_overlay.py`)
- Regime Overlay → Strategy Sleeves: combines sleeves (evidence: `scripts/regime_overlay.py`)
- Regime Overlay → Performance Metrics: evaluates results (evidence: `scripts/regime_overlay.py`)