# henryz16/skd-backtest architecture

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

- Interactive diagram: https://gitdiagram.com/henryz16/skd-backtest
- Repository: https://github.com/henryz16/skd-backtest

## Overview

skd-backtest is a daily Python backtesting framework for index-enhancement research, exposed through a single-model Python API and a batch-evaluation CLI. The main workflow loads dated market and reference data, obtains model scores, constructs portfolio targets, executes orders with costs and trading limits, values the account, then evaluates predictions and emits audit results. The graph follows the engine-owned calls visible in its excerpt and documented capabilities; several component internals and engine stages were not fully sampled, so their uncertain links are omitted.

Main entry points: [`src/skd_backtest/engine.py`](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/engine.py) (Backtest engine), [`src/skd_backtest/data_provider.py`](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/data_provider.py) (Market data provider), [`src/skd_backtest/runtime_cache.py`](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/runtime_cache.py) (Runtime cache), [`src/skd_backtest/__init__.py`](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/__init__.py) (Python API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_api["Python API<br/>[__init__.py]"]
  node_cli["CLI evaluation<br/>[evaluate.py]"]
  node_submission["Submission runner"]
  node_engine["Backtest engine<br/>[engine.py]"]
  node_config["Run configuration<br/>[config.py]"]
  node_inference["Async inference"]
end

subgraph group_market["Market and reference data"]
  node_marketdata["Market data provider<br/>[data_provider.py]"]
  node_limits["Adjusted limits<br/>[adjusted_limits.py]"]
  node_references["Reference data<br/>[reference_data.py]"]
end

subgraph group_portfolio["Portfolio and trading"]
  node_optimizer["Portfolio optimizer"]
  node_risk["Barra optimizer<br/>[risk_optimizer.py]"]
  node_broker["Order execution<br/>[broker.py]"]
  node_costs["Trading costs<br/>[cost_model.py]"]
  node_accounting["Account valuation<br/>[accounting.py]"]
end

subgraph group_evaluation["Evaluation and results"]
  node_labels["Forward labels<br/>[label_provider.py]"]
  node_metrics["Performance metrics<br/>[metrics.py]"]
  node_predictioneval["Prediction evaluation"]
  node_writer["Audit output<br/>[result_writer.py]"]
end

subgraph group_protocol["Shared runtime protocol"]
  node_cache[("Runtime cache<br/>[runtime_cache.py]")]
  node_contracts["Packet contracts<br/>[contracts.py]"]
  node_schemas["Table schemas<br/>[schemas.py]"]
end

node_researcher(("Research user"))
node_platform(("Evaluation platform"))
node_marketfiles[("Market data files")]
node_refiles[("Reference data files")]
node_results["Audit artifacts"]

node_researcher -->|"uses API"| node_api
node_api -->|"creates engine"| node_engine
node_platform -->|"invokes evaluation"| node_cli
node_cli -->|"runs backtest"| node_engine
node_engine -->|"configures run"| node_config
node_engine -->|"prepares playback"| node_marketdata
node_marketdata -->|"reads parquet"| node_marketfiles
node_marketdata -->|"uses limits"| node_limits
node_engine -->|"prepares references"| node_references
node_references -->|"reads datasets"| node_refiles
node_engine -->|"buffers inference"| node_inference
node_inference -->|"requests scores"| node_submission
node_engine -->|"requests prediction"| node_submission
node_engine -.->|"constructs targets"| node_optimizer
node_optimizer -->|"runs Barra"| node_risk
node_engine -.->|"executes trades"| node_broker
node_broker -->|"requests quote"| node_costs
node_engine -.->|"values account"| node_accounting
node_engine -.->|"builds labels"| node_labels
node_engine -.->|"evaluates predictions"| node_predictioneval
node_engine -.->|"computes metrics"| node_metrics
node_engine -.->|"writes results"| node_writer
node_writer -->|"writes artifacts"| node_results
node_engine -->|"coordinates packets"| node_cache
node_cache -->|"enforces topics"| node_contracts
node_cache -->|"validates tables"| node_schemas
node_labels -->|"reads prices"| node_marketfiles

click node_api "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/__init__.py"
click node_cli "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/evaluate.py"
click node_submission "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/submission_runner.py"
click node_engine "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/engine.py"
click node_config "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/config.py"
click node_marketdata "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/data_provider.py"
click node_limits "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/adjusted_limits.py"
click node_references "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/reference_data.py"
click node_inference "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/inference_pipeline.py"
click node_labels "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/label_provider.py"
click node_optimizer "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/portfolio_optimizer.py"
click node_risk "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/risk_optimizer.py"
click node_broker "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/broker.py"
click node_costs "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/cost_model.py"
click node_accounting "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/accounting.py"
click node_metrics "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/metrics.py"
click node_predictioneval "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/prediction_evaluator.py"
click node_writer "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/result_writer.py"
click node_cache "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/runtime_cache.py"
click node_contracts "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/contracts.py"
click node_schemas "https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/schemas.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_api,node_cli,node_submission,node_engine,node_config,node_inference,node_researcher toneBlue
class node_marketdata,node_limits,node_references,node_marketfiles,node_refiles toneAmber
class node_optimizer,node_risk,node_broker,node_costs,node_accounting toneMint
class node_labels,node_metrics,node_predictioneval,node_writer toneRose
class node_cache,node_contracts,node_schemas,node_platform,node_results toneIndigo
```

## Components

### Entry and orchestration

- [Python API](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/__init__.py): `src/skd_backtest/__init__.py`
- [CLI evaluation](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/evaluate.py): `src/skd_backtest/evaluate.py`
- [Submission runner](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/submission_runner.py): `src/skd_backtest/submission_runner.py`
- [Backtest engine](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/engine.py): `src/skd_backtest/engine.py`
- [Run configuration](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/config.py): `src/skd_backtest/config.py`
- [Async inference](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/inference_pipeline.py): `src/skd_backtest/inference_pipeline.py`

### Market and reference data

- [Market data provider](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/data_provider.py): `src/skd_backtest/data_provider.py`
- [Adjusted limits](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/adjusted_limits.py): `src/skd_backtest/adjusted_limits.py`
- [Reference data](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/reference_data.py): `src/skd_backtest/reference_data.py`

### Portfolio and trading

- [Portfolio optimizer](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/portfolio_optimizer.py): `src/skd_backtest/portfolio_optimizer.py`
- [Barra optimizer](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/risk_optimizer.py): `src/skd_backtest/risk_optimizer.py`
- [Order execution](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/broker.py): `src/skd_backtest/broker.py`
- [Trading costs](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/cost_model.py): `src/skd_backtest/cost_model.py`
- [Account valuation](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/accounting.py): `src/skd_backtest/accounting.py`

### Evaluation and results

- [Forward labels](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/label_provider.py): `src/skd_backtest/label_provider.py`
- [Performance metrics](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/metrics.py): `src/skd_backtest/metrics.py`
- [Prediction evaluation](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/prediction_evaluator.py): `src/skd_backtest/prediction_evaluator.py`
- [Audit output](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/result_writer.py): `src/skd_backtest/result_writer.py`

### Shared runtime protocol

- [Runtime cache](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/runtime_cache.py): `src/skd_backtest/runtime_cache.py`
- [Packet contracts](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/contracts.py): `src/skd_backtest/contracts.py`
- [Table schemas](https://github.com/henryz16/skd-backtest/blob/main/src/skd_backtest/schemas.py): `src/skd_backtest/schemas.py`

### Other components

- **Research user**
- **Evaluation platform**
- **Market data files**
- **Reference data files**
- **Audit artifacts**

## Connections

- Research user → Python API: uses API (evidence: `README.md`)
- Python API → Backtest engine: creates engine (evidence: `src/skd_backtest/__init__.py`)
- Evaluation platform → CLI evaluation: invokes evaluation (evidence: `README.md`)
- CLI evaluation → Backtest engine: runs backtest (evidence: `src/skd_backtest/evaluate.py`)
- Backtest engine → Run configuration: configures run (evidence: `src/skd_backtest/engine.py`)
- Backtest engine → Market data provider: prepares playback (evidence: `src/skd_backtest/engine.py`)
- Market data provider → Market data files: reads parquet (evidence: `src/skd_backtest/data_provider.py`)
- Market data provider → Adjusted limits: uses limits (evidence: `src/skd_backtest/data_provider.py`)
- Backtest engine → Reference data: prepares references (evidence: `src/skd_backtest/engine.py`)
- Reference data → Reference data files: reads datasets (evidence: `src/skd_backtest/reference_data.py`)
- Backtest engine → Async inference: buffers inference (evidence: `src/skd_backtest/engine.py`)
- Async inference → Submission runner: requests scores (evidence: `src/skd_backtest/inference_pipeline.py`)
- Backtest engine → Submission runner: requests prediction (evidence: `src/skd_backtest/engine.py`)
- Backtest engine → Portfolio optimizer: constructs targets (evidence: `src/skd_backtest/engine.py`)
- Portfolio optimizer → Barra optimizer: runs Barra (evidence: `src/skd_backtest/portfolio_optimizer.py`)
- Backtest engine → Order execution: executes trades (evidence: `src/skd_backtest/engine.py`)
- Order execution → Trading costs: requests quote (evidence: `src/skd_backtest/broker.py`)
- Backtest engine → Account valuation: values account (evidence: `src/skd_backtest/engine.py`)
- Backtest engine → Forward labels: builds labels (evidence: `src/skd_backtest/engine.py`)
- Backtest engine → Prediction evaluation: evaluates predictions (evidence: `src/skd_backtest/engine.py`)
- Backtest engine → Performance metrics: computes metrics (evidence: `src/skd_backtest/engine.py`)
- Backtest engine → Audit output: writes results (evidence: `src/skd_backtest/engine.py`)
- Audit output → Audit artifacts: writes artifacts (evidence: `README.md`)
- Backtest engine → Runtime cache: coordinates packets (evidence: `src/skd_backtest/engine.py`)
- Runtime cache → Packet contracts: enforces topics (evidence: `src/skd_backtest/runtime_cache.py`)
- Runtime cache → Table schemas: validates tables (evidence: `src/skd_backtest/runtime_cache.py`)
- Forward labels → Market data files: reads prices (evidence: `src/skd_backtest/label_provider.py`)
