# kkvamshee/strat-trading-exp architecture

> Architecture diagram of the GitHub repository kkvamshee/strat-trading-exp, 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/kkvamshee/strat-trading-exp
- Repository: https://github.com/kkvamshee/strat-trading-exp

## Overview

This is a modular crypto trading system for historical replay/backtesting and real-time paper or live trading. The principal workflow starts at the CLI, obtains candle data, builds market features, dispatches a selected strategy through risk checks, then records decisions and executes approved orders; replay also summarizes strategy performance. The graph preserves the separate market-ingestion, strategy, execution, persistence, and analytics responsibilities. README content was empty, so documented capabilities rely on the CLI excerpt; unsampled modules are included only where the source index or excerpts support them.

Main entry points: [`main.py`](https://github.com/kkvamshee/strat-trading-exp/blob/main/main.py) (Trading CLI), [`src/replay_engine.py`](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/replay_engine.py) (Historical replay), [`src/database.py`](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/database.py) (SQLite database), [`src/brain.py`](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/brain.py) (Strategy brain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Trading workflows"]
  node_cli["Trading CLI<br/>[main.py]"]
  node_replay["Historical replay<br/>[replay_engine.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_market["Market data"]
  node_connector["Coinbase connector"]
end

subgraph group_decision["Strategy decisions"]
  node_brain["Strategy brain<br/>[brain.py]"]
  node_registry["Strategy factory<br/>[registry.py]"]
  node_jev["Jev AI strategy<br/>[jev_strategy.py]"]
  node_technical["Technical strategies"]
  node_base["Strategy interface<br/>[base.py]"]
  node_models["Trading models<br/>[models.py]"]
end

subgraph group_execution["Trade execution"]
  node_paper["Paper engine<br/>[paper_engine.py]"]
  node_live["Live executor<br/>[order_executor.py]"]
end

subgraph group_state["Persistence and analytics"]
  node_database[("SQLite database<br/>[database.py]")]
  node_monitor["Trading monitor<br/>[monitor.py]"]
  node_performance["Performance tracker"]
end

node_trader(("Operator"))
node_coinbase["Coinbase API"]

node_trader -->|"invokes"| node_cli
node_cli -->|"runs replay"| node_replay
node_cli -->|"starts streaming"| node_connector
node_cli -->|"evaluates candles"| node_brain
node_cli -->|"executes paper"| node_paper
node_cli -->|"selects live"| node_live
node_cli -->|"records decisions"| node_database
node_cli -->|"loads settings"| node_config
node_replay -->|"backfills candles"| node_connector
node_connector -->|"fetches market data"| node_coinbase
node_connector -->|"stores candles"| node_database
node_replay -->|"loads history"| node_database
node_replay -->|"builds strategies"| node_registry
node_cli -->|"builds strategy"| node_registry
node_registry -->|"constructs"| node_jev
node_registry -->|"constructs"| node_technical
node_jev -->|"implements"| node_base
node_technical -->|"implements"| node_base
node_brain -->|"dispatches signal"| node_base
node_brain -->|"builds state"| node_models
node_replay -->|"evaluates history"| node_brain
node_brain -->|"returns intent"| node_models
node_replay -->|"simulates orders"| node_paper
node_paper -->|"persists portfolio"| node_database
node_live -->|"uses trading state"| node_database
node_replay -->|"summarizes runs"| node_performance
node_monitor -->|"uses market models"| node_models
node_database -->|"stores records"| node_models

click node_cli "https://github.com/kkvamshee/strat-trading-exp/blob/main/main.py"
click node_replay "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/replay_engine.py"
click node_connector "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/coinbase_connector.py"
click node_brain "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/brain.py"
click node_registry "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/registry.py"
click node_jev "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/jev_strategy.py"
click node_technical "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/technical_strategies.py"
click node_base "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/base.py"
click node_models "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/models.py"
click node_paper "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/paper_engine.py"
click node_live "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/order_executor.py"
click node_database "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/database.py"
click node_monitor "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/monitor.py"
click node_performance "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/performance_tracker.py"
click node_config "https://github.com/kkvamshee/strat-trading-exp/blob/main/src/config.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_cli,node_replay,node_config toneBlue
class node_connector toneAmber
class node_brain,node_registry,node_jev,node_technical,node_base,node_models,node_coinbase toneMint
class node_paper,node_live toneRose
class node_database,node_monitor,node_performance,node_trader toneIndigo
```

## Components

### Trading workflows

- [Trading CLI](https://github.com/kkvamshee/strat-trading-exp/blob/main/main.py): `main.py`
- [Historical replay](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/replay_engine.py): `src/replay_engine.py`
- [Configuration](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/config.py): `src/config.py`

### Market data

- [Coinbase connector](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/coinbase_connector.py): `src/coinbase_connector.py`

### Strategy decisions

- [Strategy brain](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/brain.py): `src/brain.py`
- [Strategy factory](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/registry.py): `src/strategies/registry.py`
- [Jev AI strategy](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/jev_strategy.py): `src/strategies/jev_strategy.py`
- [Technical strategies](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/technical_strategies.py): `src/strategies/technical_strategies.py`
- [Strategy interface](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/strategies/base.py): `src/strategies/base.py`
- [Trading models](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/models.py): `src/models.py`

### Trade execution

- [Paper engine](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/paper_engine.py): `src/paper_engine.py`
- [Live executor](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/order_executor.py): `src/order_executor.py`

### Persistence and analytics

- [SQLite database](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/database.py): `src/database.py`
- [Trading monitor](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/monitor.py): `src/monitor.py`
- [Performance tracker](https://github.com/kkvamshee/strat-trading-exp/blob/main/src/performance_tracker.py): `src/performance_tracker.py`

### Other components

- **Operator**
- **Coinbase API**

## Connections

- Operator → Trading CLI: invokes (evidence: `main.py`)
- Trading CLI → Historical replay: runs replay (evidence: `main.py`)
- Trading CLI → Coinbase connector: starts streaming (evidence: `main.py`)
- Trading CLI → Strategy brain: evaluates candles (evidence: `main.py`)
- Trading CLI → Paper engine: executes paper (evidence: `main.py`)
- Trading CLI → Live executor: selects live (evidence: `main.py`)
- Trading CLI → SQLite database: records decisions (evidence: `main.py`)
- Trading CLI → Configuration: loads settings (evidence: `main.py`)
- Historical replay → Coinbase connector: backfills candles (evidence: `src/replay_engine.py`)
- Coinbase connector → Coinbase API: fetches market data (evidence: `src/coinbase_connector.py`)
- Coinbase connector → SQLite database: stores candles (evidence: `src/coinbase_connector.py`)
- Historical replay → SQLite database: loads history (evidence: `src/replay_engine.py`)
- Historical replay → Strategy factory: builds strategies (evidence: `src/replay_engine.py`)
- Trading CLI → Strategy factory: builds strategy (evidence: `main.py`)
- Strategy factory → Jev AI strategy: constructs (evidence: `src/strategies/registry.py`)
- Strategy factory → Technical strategies: constructs (evidence: `src/strategies/registry.py`)
- Jev AI strategy → Strategy interface: implements (evidence: `src/strategies/jev_strategy.py`)
- Technical strategies → Strategy interface: implements (evidence: `src/strategies/technical_strategies.py`)
- Strategy brain → Strategy interface: dispatches signal (evidence: `src/brain.py`)
- Strategy brain → Trading models: builds state (evidence: `src/brain.py`)
- Historical replay → Strategy brain: evaluates history (evidence: `src/replay_engine.py`)
- Strategy brain → Trading models: returns intent (evidence: `src/brain.py`)
- Historical replay → Paper engine: simulates orders (evidence: `src/replay_engine.py`)
- Paper engine → SQLite database: persists portfolio (evidence: `src/paper_engine.py`)
- Live executor → SQLite database: uses trading state (evidence: `src/order_executor.py`)
- Historical replay → Performance tracker: summarizes runs (evidence: `src/replay_engine.py`)
- Trading monitor → Trading models: uses market models (evidence: `src/monitor.py`)
- SQLite database → Trading models: stores records (evidence: `src/database.py`)
