# lexian-6/volatility_surface_trader architecture

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

- Interactive diagram: https://gitdiagram.com/lexian-6/volatility_surface_trader
- Repository: https://github.com/lexian-6/volatility_surface_trader

## Overview

Volatility Surface Trader is a replay-based options research simulator. Users select real or synthetic market data, inspect an OTM volatility surface and option-chain edges, place trades, and review portfolio P&L and risk. The real-data path collects IBKR historical bars, merges them into replay snapshots, and loads them in the dashboard; synthetic replay is an alternative. The graph preserves documented dashboard capabilities, but several source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`vol_surface_trader/dashboard/app.py`](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/dashboard/app.py) (Interactive Dashboard), [`vol_surface_trader/core/ibkr_client.py`](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/ibkr_client.py) (IBKR Chain Client), [`vol_surface_trader/data`](https://github.com/lexian-6/volatility_surface_trader/tree/main/vol_surface_trader/data) (Replay Snapshots), [`vol_surface_trader/data/replay.py`](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/data/replay.py) (Historical Replay Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Market Data Collection"]
  node_history["Historical Bar Collector<br/>[collect_history.py]"]
  node_merge["Snapshot Merger<br/>[merge_history.py]"]
  node_stream["Live Chain Collector<br/>[stream_chain.py]"]
  node_ibclient["IBKR Chain Client<br/>[ibkr_client.py]"]
end

subgraph group_replay["Replay Data"]
  node_snapshot_files[("Replay Snapshots")]
  node_replay_server["Historical Replay Server<br/>[replay.py]"]
  node_synthetic["Synthetic Session Generator<br/>[replay_engine.py]"]
  node_engine["Trading Replay Engine<br/>[replay_engine.py]"]
end

subgraph group_analytics["Volatility Analytics"]
  node_pricing["Option Pricing<br/>[pricing.py]"]
  node_surface["IV Surface And Edges<br/>[vol_surface.py]"]
end

subgraph group_trading["Trading And Risk"]
  node_models["Market And Trade Models<br/>[models.py]"]
  node_portfolio["Positions And Risk<br/>[portfolio.py]"]
end

subgraph group_ui["Dashboard"]
  node_dashboard["Interactive Dashboard<br/>[app.py]"]
  node_viz["Surface Visualization<br/>[visualization.py]"]
end

node_user(("Researcher"))
node_ibkr(("IBKR TWS / Gateway"))

node_user -->|"selects and trades"| node_dashboard
node_ibkr -->|"historical bars"| node_history
node_history -->|"writes bar files"| node_merge
node_merge -->|"writes snapshots"| node_snapshot_files
node_ibkr -.->|"live quotes"| node_stream
node_stream -.->|"writes snapshots"| node_snapshot_files
node_ibkr -.->|"market data"| node_ibclient
node_snapshot_files -->|"loads snapshots"| node_replay_server
node_dashboard -->|"selects real replay"| node_replay_server
node_dashboard -->|"requests simulation"| node_synthetic
node_synthetic -->|"generates session states"| node_engine
node_replay_server -->|"emits snapshots"| node_dashboard
node_dashboard -->|"controls playback and trades"| node_engine
node_engine -->|"updates positions and P&amp;L"| node_portfolio
node_portfolio -->|"calculates option Greeks"| node_pricing
node_dashboard -->|"builds OTM surface and edges"| node_surface
node_surface -->|"solves implied volatility"| node_pricing
node_dashboard -->|"renders analysis"| node_viz
node_dashboard -.->|"requests chain data"| node_ibclient
node_ibclient -.->|"requests quotes and contracts"| node_ibkr

click node_history "https://github.com/lexian-6/volatility_surface_trader/blob/main/ib_chain_collector/collect_history.py"
click node_merge "https://github.com/lexian-6/volatility_surface_trader/blob/main/ib_chain_collector/merge_history.py"
click node_stream "https://github.com/lexian-6/volatility_surface_trader/blob/main/ib_chain_collector/stream_chain.py"
click node_snapshot_files "https://github.com/lexian-6/volatility_surface_trader/tree/main/vol_surface_trader/data"
click node_replay_server "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/data/replay.py"
click node_synthetic "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/replay_engine.py"
click node_engine "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/replay_engine.py"
click node_models "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/models.py"
click node_pricing "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/pricing.py"
click node_surface "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/vol_surface.py"
click node_portfolio "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/portfolio.py"
click node_dashboard "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/dashboard/app.py"
click node_viz "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/dashboard/visualization.py"
click node_ibclient "https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/ibkr_client.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_history,node_merge,node_stream,node_ibclient toneBlue
class node_snapshot_files,node_replay_server,node_synthetic,node_engine toneAmber
class node_pricing,node_surface toneMint
class node_models,node_portfolio toneRose
class node_dashboard,node_viz,node_user,node_ibkr toneIndigo
```

## Components

### Market Data Collection

- [Historical Bar Collector](https://github.com/lexian-6/volatility_surface_trader/blob/main/ib_chain_collector/collect_history.py): `ib_chain_collector/collect_history.py`
- [Snapshot Merger](https://github.com/lexian-6/volatility_surface_trader/blob/main/ib_chain_collector/merge_history.py): `ib_chain_collector/merge_history.py`
- [Live Chain Collector](https://github.com/lexian-6/volatility_surface_trader/blob/main/ib_chain_collector/stream_chain.py): `ib_chain_collector/stream_chain.py`
- [IBKR Chain Client](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/ibkr_client.py): `vol_surface_trader/core/ibkr_client.py`

### Replay Data

- [Replay Snapshots](https://github.com/lexian-6/volatility_surface_trader/tree/main/vol_surface_trader/data): `vol_surface_trader/data`
- [Historical Replay Server](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/data/replay.py): `vol_surface_trader/data/replay.py`
- [Synthetic Session Generator](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/replay_engine.py): `vol_surface_trader/core/replay_engine.py`
- [Trading Replay Engine](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/replay_engine.py): `vol_surface_trader/core/replay_engine.py`

### Volatility Analytics

- [Option Pricing](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/pricing.py): `vol_surface_trader/core/pricing.py`
- [IV Surface And Edges](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/vol_surface.py): `vol_surface_trader/core/vol_surface.py`

### Trading And Risk

- [Market And Trade Models](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/models.py): `vol_surface_trader/core/models.py`
- [Positions And Risk](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/core/portfolio.py): `vol_surface_trader/core/portfolio.py`

### Dashboard

- [Interactive Dashboard](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/dashboard/app.py): `vol_surface_trader/dashboard/app.py`
- [Surface Visualization](https://github.com/lexian-6/volatility_surface_trader/blob/main/vol_surface_trader/dashboard/visualization.py): `vol_surface_trader/dashboard/visualization.py`

### Other components

- **Researcher**
- **IBKR TWS / Gateway**

## Connections

- Researcher → Interactive Dashboard: selects and trades
- IBKR TWS / Gateway → Historical Bar Collector: historical bars
- Historical Bar Collector → Snapshot Merger: writes bar files
- Snapshot Merger → Replay Snapshots: writes snapshots
- IBKR TWS / Gateway → Live Chain Collector: live quotes
- Live Chain Collector → Replay Snapshots: writes snapshots
- IBKR TWS / Gateway → IBKR Chain Client: market data
- Replay Snapshots → Historical Replay Server: loads snapshots
- Interactive Dashboard → Historical Replay Server: selects real replay
- Interactive Dashboard → Synthetic Session Generator: requests simulation
- Synthetic Session Generator → Trading Replay Engine: generates session states
- Historical Replay Server → Interactive Dashboard: emits snapshots
- Interactive Dashboard → Trading Replay Engine: controls playback and trades
- Trading Replay Engine → Positions And Risk: updates positions and P&L
- Positions And Risk → Option Pricing: calculates option Greeks
- Interactive Dashboard → IV Surface And Edges: builds OTM surface and edges
- IV Surface And Edges → Option Pricing: solves implied volatility
- Interactive Dashboard → Surface Visualization: renders analysis
- Interactive Dashboard → IBKR Chain Client: requests chain data
- IBKR Chain Client → IBKR TWS / Gateway: requests quotes and contracts