# zhaorongdai/quantlab architecture

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

- Interactive diagram: https://gitdiagram.com/zhaorongdai/quantlab
- Repository: https://github.com/zhaorongdai/quantlab

## Overview

quantlab is a quantitative-equity research backend: users acquire market data, build timestamp-by-symbol panels, derive factors and forward-return labels, train predictive models, and backtest resulting portfolios. Its common panel/storage layer supports that workflow, while factor analysis and run reporting provide research outputs. The README documents the stage sequence and major capabilities; source excerpts and the index support the internal storage, factor, configuration, and backtest links shown. Some implementation details were not sampled, so uncertain connections are omitted.

Main entry points: [`quantlab/base/factor.py`](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/factor.py) (Factor layer), [`quantlab/base/backtest.py`](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/backtest.py) (Backtesting), [`quantlab/base/data.py`](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/data.py) (Panel datasets), [`quantlab/base/model.py`](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/model.py) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_acquisition["Acquisition<br/>[acquisition.py]"]
  node_vendor_adapters["Vendor adapters"]
end

subgraph group_research["Research data"]
  node_datasets["Panel datasets<br/>[data.py]"]
  node_stock_dataset["Stock dataset<br/>[stock.py]"]
  node_crsp_universe["CRSP universes"]
  node_factor_base["Factor layer<br/>[factor.py]"]
  node_factor_engines["Factor engines"]
  node_labels["Forward labels<br/>[forward.py]"]
  node_factor_analysis["Factor analysis<br/>[factor_report.py]"]
end

subgraph group_learning["Modeling"]
  node_models["Models<br/>[model.py]"]
  node_model_implementations["Model implementations"]
end

subgraph group_portfolio["Portfolio evaluation"]
  node_portfolio_rules["Portfolio construction<br/>[portfolio.py]"]
  node_backtesting["Backtesting<br/>[backtest.py]"]
  node_backtest_engine["Vectorbt engine<br/>[engine_vectorbt.py]"]
  node_reports["Run reports<br/>[backtest_report.py]"]
end

subgraph group_core["Shared infrastructure"]
  node_panel_storage[("Panel storage<br/>[backend.py]")]
  node_config["Pipeline configuration<br/>[config.py]"]
  node_data_vocabulary["Data vocabulary<br/>[data.py]"]
  node_tracking["Experiment tracking<br/>[tracking.py]"]
  node_utilities["Panel utilities<br/>[symbol_axis.py]"]
  node_date_ranges["Date ranges<br/>[date_range.py]"]
  node_atomic_writes["Atomic JSON writes<br/>[atomic.py]"]
  node_json_serialization["JSON serialization<br/>[jsonable.py]"]
  node_timing["Timing<br/>[timer.py]"]
end

node_researcher(("Researcher"))
node_vendors(("Market vendors"))

node_researcher -->|"requests data"| node_acquisition
node_vendors -->|"provides data"| node_vendor_adapters
node_vendor_adapters -->|"implements adapters"| node_acquisition
node_acquisition -->|"supplies raw files"| node_datasets
node_datasets -->|"specializes"| node_stock_dataset
node_datasets -->|"persists panels"| node_panel_storage
node_stock_dataset -.->|"uses historical membership"| node_crsp_universe
node_researcher -->|"requests panels"| node_datasets
node_datasets -->|"provides panels"| node_factor_base
node_factor_base -->|"uses factor backend"| node_factor_engines
node_factor_base -->|"analyzes factors"| node_factor_analysis
node_researcher -->|"requests features"| node_factor_base
node_factor_base -->|"wraps as targets"| node_labels
node_factor_base -->|"provides features"| node_models
node_labels -->|"provides targets"| node_models
node_models -->|"dispatches training"| node_model_implementations
node_researcher -->|"trains predictors"| node_models
node_models -->|"provides predictions"| node_backtesting
node_stock_dataset -->|"provides prices"| node_backtesting
node_backtesting -->|"constructs weights"| node_portfolio_rules
node_backtesting -->|"simulates weights"| node_backtest_engine
node_backtesting -->|"writes run report"| node_reports
node_backtesting -.->|"logs run records"| node_tracking
node_researcher -->|"runs evaluation"| node_backtesting
node_config -->|"configures datasets"| node_datasets
node_config -->|"configures factors"| node_factor_base
node_config -->|"configures models"| node_models
node_config -->|"configures backtests"| node_backtesting
node_data_vocabulary -->|"defines data types"| node_config
node_datasets -->|"aligns symbol axes"| node_utilities
node_factor_base -->|"uses date ranges"| node_date_ranges
node_models -.->|"records experiments"| node_tracking
node_factor_base -->|"persists metadata"| node_atomic_writes
node_backtesting -->|"persists run state"| node_atomic_writes
node_tracking -->|"serializes metrics"| node_json_serialization
node_factor_engines -->|"times computation"| node_timing

click node_acquisition "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/acquisition.py"
click node_vendor_adapters "https://github.com/zhaorongdai/quantlab/tree/main/quantlab/acquisition"
click node_datasets "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/data.py"
click node_stock_dataset "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/dataset/stock.py"
click node_crsp_universe "https://github.com/zhaorongdai/quantlab/tree/main/quantlab/dataset/crsp"
click node_panel_storage "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/backend.py"
click node_factor_base "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/factor.py"
click node_factor_engines "https://github.com/zhaorongdai/quantlab/tree/main/quantlab/factor"
click node_labels "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/label/forward.py"
click node_factor_analysis "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/analysis/factor_report.py"
click node_models "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/model.py"
click node_model_implementations "https://github.com/zhaorongdai/quantlab/tree/main/quantlab/model"
click node_portfolio_rules "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/portfolio.py"
click node_backtesting "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/backtest.py"
click node_backtest_engine "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/backtest/engine_vectorbt.py"
click node_reports "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/backtest_report.py"
click node_config "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/config.py"
click node_data_vocabulary "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/enums/data.py"
click node_tracking "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/tracking.py"
click node_utilities "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/symbol_axis.py"
click node_date_ranges "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/date_range.py"
click node_atomic_writes "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/atomic.py"
click node_json_serialization "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/jsonable.py"
click node_timing "https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/timer.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_acquisition,node_vendor_adapters toneBlue
class node_datasets,node_stock_dataset,node_crsp_universe,node_factor_base,node_factor_engines,node_labels,node_factor_analysis toneAmber
class node_models,node_model_implementations toneMint
class node_portfolio_rules,node_backtesting,node_backtest_engine,node_reports toneRose
class node_panel_storage,node_config,node_data_vocabulary,node_tracking,node_utilities,node_date_ranges,node_atomic_writes,node_json_serialization,node_timing,node_researcher,node_vendors toneIndigo
```

## Components

### Data ingestion

- [Acquisition](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/acquisition.py): `quantlab/base/acquisition.py`
- [Vendor adapters](https://github.com/zhaorongdai/quantlab/tree/main/quantlab/acquisition): `quantlab/acquisition`

### Research data

- [Panel datasets](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/data.py): `quantlab/base/data.py`
- [Stock dataset](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/dataset/stock.py): `quantlab/dataset/stock.py`
- [CRSP universes](https://github.com/zhaorongdai/quantlab/tree/main/quantlab/dataset/crsp): `quantlab/dataset/crsp`
- [Factor layer](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/factor.py): `quantlab/base/factor.py`
- [Factor engines](https://github.com/zhaorongdai/quantlab/tree/main/quantlab/factor): `quantlab/factor`
- [Forward labels](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/label/forward.py): `quantlab/label/forward.py`
- [Factor analysis](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/analysis/factor_report.py): `quantlab/analysis/factor_report.py`

### Modeling

- [Models](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/model.py): `quantlab/base/model.py`
- [Model implementations](https://github.com/zhaorongdai/quantlab/tree/main/quantlab/model): `quantlab/model`

### Portfolio evaluation

- [Portfolio construction](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/portfolio.py): `quantlab/base/portfolio.py`
- [Backtesting](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/backtest.py): `quantlab/base/backtest.py`
- [Vectorbt engine](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/backtest/engine_vectorbt.py): `quantlab/backtest/engine_vectorbt.py`
- [Run reports](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/backtest_report.py): `quantlab/utils/backtest_report.py`

### Shared infrastructure

- [Panel storage](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/backend.py): `quantlab/backend.py`
- [Pipeline configuration](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/config.py): `quantlab/base/config.py`
- [Data vocabulary](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/enums/data.py): `quantlab/enums/data.py`
- [Experiment tracking](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/base/tracking.py): `quantlab/base/tracking.py`
- [Panel utilities](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/symbol_axis.py): `quantlab/utils/symbol_axis.py`
- [Date ranges](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/date_range.py): `quantlab/utils/date_range.py`
- [Atomic JSON writes](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/atomic.py): `quantlab/utils/atomic.py`
- [JSON serialization](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/jsonable.py): `quantlab/utils/jsonable.py`
- [Timing](https://github.com/zhaorongdai/quantlab/blob/main/quantlab/utils/timer.py): `quantlab/utils/timer.py`

### Other components

- **Researcher**
- **Market vendors**

## Connections

- Researcher → Acquisition: requests data (evidence: `README.md`)
- Market vendors → Vendor adapters: provides data (evidence: `README.md`)
- Vendor adapters → Acquisition: implements adapters (evidence: `quantlab/acquisition/alpaca.py`)
- Acquisition → Panel datasets: supplies raw files (evidence: `README.md`)
- Panel datasets → Stock dataset: specializes (evidence: `quantlab/dataset/stock.py`)
- Panel datasets → Panel storage: persists panels (evidence: `quantlab/base/data.py`)
- Stock dataset → CRSP universes: uses historical membership (evidence: `quantlab/dataset/crsp/__init__.py`)
- Researcher → Panel datasets: requests panels (evidence: `README.md`)
- Panel datasets → Factor layer: provides panels (evidence: `README.md`)
- Factor layer → Factor engines: uses factor backend (evidence: `quantlab/factor/kunquant.py`)
- Factor layer → Factor analysis: analyzes factors (evidence: `quantlab/base/factor.py`)
- Researcher → Factor layer: requests features (evidence: `README.md`)
- Factor layer → Forward labels: wraps as targets (evidence: `quantlab/base/factor.py`)
- Factor layer → Models: provides features (evidence: `README.md`)
- Forward labels → Models: provides targets (evidence: `README.md`)
- Models → Model implementations: dispatches training (evidence: `quantlab/model/predefined/xgb.py`)
- Researcher → Models: trains predictors (evidence: `README.md`)
- Models → Backtesting: provides predictions (evidence: `README.md`)
- Stock dataset → Backtesting: provides prices (evidence: `README.md`)
- Backtesting → Portfolio construction: constructs weights (evidence: `quantlab/base/backtest.py`)
- Backtesting → Vectorbt engine: simulates weights (evidence: `quantlab/base/backtest.py`)
- Backtesting → Run reports: writes run report (evidence: `README.md`)
- Backtesting → Experiment tracking: logs run records (evidence: `quantlab/base/backtest.py`)
- Researcher → Backtesting: runs evaluation (evidence: `README.md`)
- Pipeline configuration → Panel datasets: configures datasets (evidence: `quantlab/base/config.py`)
- Pipeline configuration → Factor layer: configures factors (evidence: `quantlab/base/config.py`)
- Pipeline configuration → Models: configures models (evidence: `quantlab/base/config.py`)
- Pipeline configuration → Backtesting: configures backtests (evidence: `quantlab/base/config.py`)
- Data vocabulary → Pipeline configuration: defines data types (evidence: `quantlab/base/config.py`)
- Panel datasets → Panel utilities: aligns symbol axes (evidence: `quantlab/base/data.py`)
- Factor layer → Date ranges: uses date ranges (evidence: `quantlab/base/factor.py`)
- Models → Experiment tracking: records experiments (evidence: `quantlab/base/model.py`)
- Factor layer → Atomic JSON writes: persists metadata (evidence: `quantlab/base/factor.py`)
- Backtesting → Atomic JSON writes: persists run state (evidence: `quantlab/base/backtest.py`)
- Experiment tracking → JSON serialization: serializes metrics (evidence: `quantlab/base/tracking.py`)
- Factor engines → Timing: times computation (evidence: `quantlab/factor/kunquant.py`)
