# quanttqueensu/ls_gamma architecture

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

- Interactive diagram: https://gitdiagram.com/quanttqueensu/ls_gamma
- Repository: https://github.com/quanttqueensu/ls_gamma

## Overview

QUANTT is a research and paper-trading system for regime-dependent SPY options gamma scalping. The paper workflow builds a market snapshot, forecasts realized volatility, derives a VRP signal, selects and manages option positions, and sends orders through an IBKR paper-trading guard. A separate historical workflow builds replay snapshots and runs backtests that produce metrics and reports. The README documents the major strategies and research capabilities; several implementation details are unsampled, so those links are omitted or shown as unverified.

Main entry points: [`src/lsgamma/trading/runner.py`](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/runner.py) (Daily runner), [`src/lsgamma/pipeline/build.py`](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/build.py) (Snapshot builder), [`src/lsgamma/backtest/run.py`](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/run.py) (Backtest runner), [`src/lsgamma/pipeline/store.py`](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/store.py) (Snapshot store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market_data["Market data"]
  node_snapshot_build["Snapshot builder<br/>[build.py]"]
  node_option_chain["Option chain<br/>[chain.py]"]
  node_market_features["Market features<br/>[features.py]"]
  node_snapshot_store[("Snapshot store<br/>[store.py]")]
  node_history_replay["History builder<br/>[build.py]"]
end

subgraph group_decision["Forecasts and signals"]
  node_rv_forecasters["RV forecasters"]
  node_vrp_signal["VRP signal<br/>[vrp_band.py]"]
end

subgraph group_trading["Paper trading"]
  node_daily_runner["Daily runner<br/>[runner.py]"]
  node_trade_selection["Trade selection<br/>[selection.py]"]
  node_position_exits["Exit rules<br/>[exits.py]"]
  node_pnl_calc["P&amp;L calculation<br/>[pnl.py]"]
  node_trade_ledger[("Trade ledger<br/>[ledger.py]")]
end

subgraph group_research["Backtests and research"]
  node_backtest_engine["Backtest engine<br/>[engine.py]"]
  node_backtest_config["Backtest config<br/>[config.py]"]
  node_backtest_run["Backtest runner<br/>[run.py]"]
  node_backtest_metrics["Metrics and reports<br/>[report.py]"]
  node_experiment_log[("Experiment log<br/>[experiments.py]")]
end

subgraph group_execution["Option strategies"]
  node_hedging["Delta hedging"]
  node_option_strategies["Option strategies"]
  node_ibkr_broker["IBKR paper broker<br/>[broker.py]"]
end

node_market_sources(("Market sources"))
node_history_inputs[("Historical data")]

node_market_sources -.->|"supplies data"| node_snapshot_build
node_snapshot_build -.->|"builds chain"| node_option_chain
node_snapshot_build -.->|"builds features"| node_market_features
node_snapshot_build -.->|"stores snapshot"| node_snapshot_store
node_history_inputs -->|"replays trades"| node_history_replay
node_history_replay -->|"uses features"| node_market_features
node_history_replay -->|"writes snapshots"| node_snapshot_store
node_daily_runner -->|"runs pipeline"| node_snapshot_build
node_daily_runner -->|"reads snapshot"| node_snapshot_store
node_daily_runner -->|"forecasts volatility"| node_rv_forecasters
node_daily_runner -->|"computes signal"| node_vrp_signal
node_daily_runner -->|"selects contracts"| node_trade_selection
node_daily_runner -->|"checks exits"| node_position_exits
node_position_exits -->|"uses P&amp;L"| node_pnl_calc
node_daily_runner -->|"calculates P&amp;L"| node_pnl_calc
node_daily_runner -->|"records trades"| node_trade_ledger
node_daily_runner -->|"requests hedges"| node_hedging
node_daily_runner -->|"executes positions"| node_option_strategies
node_option_strategies -->|"submits orders"| node_ibkr_broker
node_hedging -->|"submits stock orders"| node_ibkr_broker
node_backtest_config -->|"loads experiment config"| node_experiment_log
node_backtest_run -->|"runs simulation"| node_backtest_engine
node_backtest_run -->|"loads settings"| node_backtest_config
node_backtest_engine -->|"reads snapshots"| node_snapshot_store
node_backtest_run -->|"summarizes results"| node_backtest_metrics
node_backtest_metrics -->|"reports runs"| node_backtest_engine
node_backtest_run -->|"saves trials"| node_experiment_log

click node_snapshot_build "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/build.py"
click node_option_chain "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/chain.py"
click node_market_features "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/features.py"
click node_snapshot_store "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/store.py"
click node_history_replay "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/history/build.py"
click node_rv_forecasters "https://github.com/quanttqueensu/ls_gamma/tree/main/src/lsgamma/forecasting"
click node_vrp_signal "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/signals/vrp_band.py"
click node_daily_runner "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/runner.py"
click node_trade_selection "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/selection.py"
click node_position_exits "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/exits.py"
click node_pnl_calc "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/pnl.py"
click node_trade_ledger "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/ledger.py"
click node_hedging "https://github.com/quanttqueensu/ls_gamma/tree/main/src/lsgamma/core/Algos/Hedging"
click node_option_strategies "https://github.com/quanttqueensu/ls_gamma/tree/main/src/lsgamma/core/Algos"
click node_ibkr_broker "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/core/Algos/broker.py"
click node_backtest_engine "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/engine.py"
click node_backtest_config "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/config.py"
click node_backtest_run "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/run.py"
click node_backtest_metrics "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/report.py"
click node_experiment_log "https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/experiments.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_snapshot_build,node_option_chain,node_market_features,node_snapshot_store,node_history_replay toneBlue
class node_rv_forecasters,node_vrp_signal,node_history_inputs toneAmber
class node_daily_runner,node_trade_selection,node_position_exits,node_pnl_calc,node_trade_ledger toneMint
class node_backtest_engine,node_backtest_config,node_backtest_run,node_backtest_metrics,node_experiment_log toneRose
class node_hedging,node_option_strategies,node_ibkr_broker,node_market_sources toneIndigo
```

## Components

### Market data

- [Snapshot builder](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/build.py): `src/lsgamma/pipeline/build.py`
- [Option chain](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/chain.py): `src/lsgamma/pipeline/chain.py`
- [Market features](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/features.py): `src/lsgamma/pipeline/features.py`
- [Snapshot store](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/pipeline/store.py): `src/lsgamma/pipeline/store.py`
- [History builder](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/history/build.py): `src/lsgamma/history/build.py`

### Forecasts and signals

- [RV forecasters](https://github.com/quanttqueensu/ls_gamma/tree/main/src/lsgamma/forecasting): `src/lsgamma/forecasting`
- [VRP signal](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/signals/vrp_band.py): `src/lsgamma/signals/vrp_band.py`

### Paper trading

- [Daily runner](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/runner.py): `src/lsgamma/trading/runner.py`
- [Trade selection](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/selection.py): `src/lsgamma/trading/selection.py`
- [Exit rules](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/exits.py): `src/lsgamma/trading/exits.py`
- [P&L calculation](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/pnl.py): `src/lsgamma/trading/pnl.py`
- [Trade ledger](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/trading/ledger.py): `src/lsgamma/trading/ledger.py`

### Backtests and research

- [Backtest engine](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/engine.py): `src/lsgamma/backtest/engine.py`
- [Backtest config](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/config.py): `src/lsgamma/backtest/config.py`
- [Backtest runner](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/run.py): `src/lsgamma/backtest/run.py`
- [Metrics and reports](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/backtest/report.py): `src/lsgamma/backtest/report.py`
- [Experiment log](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/experiments.py): `src/lsgamma/experiments.py`

### Option strategies

- [Delta hedging](https://github.com/quanttqueensu/ls_gamma/tree/main/src/lsgamma/core/Algos/Hedging): `src/lsgamma/core/Algos/Hedging`
- [Option strategies](https://github.com/quanttqueensu/ls_gamma/tree/main/src/lsgamma/core/Algos): `src/lsgamma/core/Algos`
- [IBKR paper broker](https://github.com/quanttqueensu/ls_gamma/blob/main/src/lsgamma/core/Algos/broker.py): `src/lsgamma/core/Algos/broker.py`

### Other components

- **Market sources**
- **Historical data**

## Connections

- Market sources → Snapshot builder: supplies data
- Snapshot builder → Option chain: builds chain
- Snapshot builder → Market features: builds features
- Snapshot builder → Snapshot store: stores snapshot
- Historical data → History builder: replays trades (evidence: `src/lsgamma/history/build.py`)
- History builder → Market features: uses features (evidence: `src/lsgamma/history/build.py`)
- History builder → Snapshot store: writes snapshots (evidence: `src/lsgamma/history/build.py`)
- Daily runner → Snapshot builder: runs pipeline (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → Snapshot store: reads snapshot (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → RV forecasters: forecasts volatility (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → VRP signal: computes signal (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → Trade selection: selects contracts (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → Exit rules: checks exits (evidence: `src/lsgamma/trading/runner.py`)
- Exit rules → P&L calculation: uses P&L (evidence: `src/lsgamma/trading/exits.py`)
- Daily runner → P&L calculation: calculates P&L (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → Trade ledger: records trades (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → Delta hedging: requests hedges (evidence: `src/lsgamma/trading/runner.py`)
- Daily runner → Option strategies: executes positions (evidence: `src/lsgamma/trading/runner.py`)
- Option strategies → IBKR paper broker: submits orders (evidence: `src/lsgamma/core/Algos/Hedging/portfolio.py`)
- Delta hedging → IBKR paper broker: submits stock orders (evidence: `src/lsgamma/core/Algos/broker.py`)
- Backtest config → Experiment log: loads experiment config (evidence: `src/lsgamma/backtest/config.py`)
- Backtest runner → Backtest engine: runs simulation (evidence: `src/lsgamma/backtest/run.py`)
- Backtest runner → Backtest config: loads settings (evidence: `src/lsgamma/backtest/run.py`)
- Backtest engine → Snapshot store: reads snapshots (evidence: `src/lsgamma/backtest/engine.py`)
- Backtest runner → Metrics and reports: summarizes results (evidence: `src/lsgamma/backtest/run.py`)
- Metrics and reports → Backtest engine: reports runs (evidence: `src/lsgamma/backtest/report.py`)
- Backtest runner → Experiment log: saves trials (evidence: `src/lsgamma/backtest/run.py`)
