# dhritij27/quant-signal-backtest architecture

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

## Overview

This is a quant research pipeline for evaluating a value/quality investment signal, not a live trading system. The principal workflow selects synthetic or real market data, scores point-in-time fundamentals, constructs and evaluates a rebalanced portfolio, applies turnover costs, and reports gross/net performance and statistics. The graph separates the engine’s snapshot, portfolio, and return responsibilities. Source excerpts show the engine, signal, loaders, and CLI wiring; README statements support the broader documented capabilities. Real-data survivorship and filing-date limitations remain as documented.

Main entry points: [`scripts/run_backtest.py`](https://github.com/dhritij27/quant-signal-backtest/blob/main/scripts/run_backtest.py) (Backtest CLI), [`backtest/engine.py`](https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/engine.py) (PIT snapshot), [`data/loader.py`](https://github.com/dhritij27/quant-signal-backtest/blob/main/data/loader.py) (Real data loader), [`signals/quality_value.py`](https://github.com/dhritij27/quant-signal-backtest/blob/main/signals/quality_value.py) (Value-quality composite)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Run orchestration"]
  node_runner["Backtest CLI<br/>[run_backtest.py]"]
  node_configuration["Run configuration<br/>[config.py]"]
end

subgraph group_data["Market data"]
  node_synthetic["Synthetic generator<br/>[synthetic.py]"]
  node_real_loader["Real data loader<br/>[loader.py]"]
end

subgraph group_signal["Signal research"]
  node_signal_impl["Value-quality composite<br/>[quality_value.py]"]
  node_signal_base["Signal transforms<br/>[base.py]"]
end

subgraph group_backtest["Portfolio evaluation"]
  node_pit["PIT snapshot<br/>[engine.py]"]
  node_portfolio["Portfolio construction<br/>[engine.py]"]
  node_returns["Period returns<br/>[engine.py]"]
  node_costs["Turnover costs<br/>[costs.py]"]
  node_metrics["Performance statistics<br/>[metrics.py]"]
  node_results["Return series and summaries<br/>[run_backtest.py]"]
end

node_researcher(("Researcher"))
node_wiki["Wikipedia constituents"]
node_yfinance["Yahoo Finance"]

node_researcher -->|"runs mode"| node_runner
node_runner -->|"loads defaults"| node_configuration
node_runner -->|"generates data"| node_synthetic
node_runner -->|"loads real data"| node_real_loader
node_real_loader -->|"fetches constituents"| node_wiki
node_real_loader -->|"fetches prices and fundamentals"| node_yfinance
node_runner -->|"creates signal"| node_signal_impl
node_runner -->|"runs engine"| node_pit
node_pit -->|"scores snapshot"| node_signal_impl
node_signal_impl -->|"uses transforms"| node_signal_base
node_pit -->|"constructs weights"| node_portfolio
node_pit -->|"calculates returns"| node_returns
node_pit -->|"computes turnover and costs"| node_costs
node_pit -->|"summarizes performance"| node_metrics
node_runner -->|"prints and saves"| node_results

click node_runner "https://github.com/dhritij27/quant-signal-backtest/blob/main/scripts/run_backtest.py"
click node_configuration "https://github.com/dhritij27/quant-signal-backtest/blob/main/config.py"
click node_synthetic "https://github.com/dhritij27/quant-signal-backtest/blob/main/data/synthetic.py"
click node_real_loader "https://github.com/dhritij27/quant-signal-backtest/blob/main/data/loader.py"
click node_pit "https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/engine.py"
click node_signal_impl "https://github.com/dhritij27/quant-signal-backtest/blob/main/signals/quality_value.py"
click node_signal_base "https://github.com/dhritij27/quant-signal-backtest/blob/main/signals/base.py"
click node_portfolio "https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/engine.py"
click node_returns "https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/engine.py"
click node_costs "https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/costs.py"
click node_metrics "https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/metrics.py"
click node_results "https://github.com/dhritij27/quant-signal-backtest/blob/main/scripts/run_backtest.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_runner,node_configuration toneBlue
class node_synthetic,node_real_loader toneAmber
class node_signal_impl,node_signal_base toneMint
class node_pit,node_portfolio,node_returns,node_costs,node_metrics,node_results toneRose
class node_researcher,node_wiki,node_yfinance toneIndigo
```

## Components

### Run orchestration

- [Backtest CLI](https://github.com/dhritij27/quant-signal-backtest/blob/main/scripts/run_backtest.py): `scripts/run_backtest.py`
- [Run configuration](https://github.com/dhritij27/quant-signal-backtest/blob/main/config.py): `config.py`

### Market data

- [Synthetic generator](https://github.com/dhritij27/quant-signal-backtest/blob/main/data/synthetic.py): `data/synthetic.py`
- [Real data loader](https://github.com/dhritij27/quant-signal-backtest/blob/main/data/loader.py): `data/loader.py`

### Signal research

- [Value-quality composite](https://github.com/dhritij27/quant-signal-backtest/blob/main/signals/quality_value.py): `signals/quality_value.py`
- [Signal transforms](https://github.com/dhritij27/quant-signal-backtest/blob/main/signals/base.py): `signals/base.py`

### Portfolio evaluation

- [PIT snapshot](https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/engine.py): `backtest/engine.py`
- [Portfolio construction](https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/engine.py): `backtest/engine.py`
- [Period returns](https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/engine.py): `backtest/engine.py`
- [Turnover costs](https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/costs.py): `backtest/costs.py`
- [Performance statistics](https://github.com/dhritij27/quant-signal-backtest/blob/main/backtest/metrics.py): `backtest/metrics.py`
- [Return series and summaries](https://github.com/dhritij27/quant-signal-backtest/blob/main/scripts/run_backtest.py): `scripts/run_backtest.py`

### Other components

- **Researcher**
- **Wikipedia constituents**
- **Yahoo Finance**

## Connections

- Researcher → Backtest CLI: runs mode (evidence: `README.md`)
- Backtest CLI → Run configuration: loads defaults (evidence: `scripts/run_backtest.py`)
- Backtest CLI → Synthetic generator: generates data (evidence: `scripts/run_backtest.py`)
- Backtest CLI → Real data loader: loads real data (evidence: `scripts/run_backtest.py`)
- Real data loader → Wikipedia constituents: fetches constituents (evidence: `data/loader.py`)
- Real data loader → Yahoo Finance: fetches prices and fundamentals (evidence: `data/loader.py`)
- Backtest CLI → Value-quality composite: creates signal (evidence: `scripts/run_backtest.py`)
- Backtest CLI → PIT snapshot: runs engine (evidence: `scripts/run_backtest.py`)
- PIT snapshot → Value-quality composite: scores snapshot (evidence: `backtest/engine.py`)
- Value-quality composite → Signal transforms: uses transforms (evidence: `signals/quality_value.py`)
- PIT snapshot → Portfolio construction: constructs weights (evidence: `backtest/engine.py`)
- PIT snapshot → Period returns: calculates returns (evidence: `backtest/engine.py`)
- PIT snapshot → Turnover costs: computes turnover and costs (evidence: `backtest/engine.py`)
- PIT snapshot → Performance statistics: summarizes performance (evidence: `backtest/engine.py`)
- Backtest CLI → Return series and summaries: prints and saves (evidence: `scripts/run_backtest.py`)