# user-nmmmmm/quanttradingv2 architecture

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

- Interactive diagram: https://gitdiagram.com/user-nmmmmm/quanttradingv2
- Repository: https://github.com/user-nmmmmm/quanttradingv2

## Overview

Still Water QuantTrading is a Python quantitative-trading research framework whose main workflow runs from market data through regime detection, strategy routing, portfolio allocation and risk controls to simulated or live execution and reporting. Backtesting uses aligned historical bars and next-bar execution; live trading adds polling, account/order reconciliation, durable state and safety gates. The README also documents data-source adapters, research validation, signal-analysis capabilities and a read-only operations dashboard. Some connections below are documented only at the architecture level; unsampled implementation details are not inferred.

Main entry points: [`core/runtime.py`](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/runtime.py) (Event Processor), [`live_trading/engine.py`](https://github.com/user-nmmmmm/quanttradingv2/blob/main/live_trading/engine.py) (Live Engine), [`backtest/engine.py`](https://github.com/user-nmmmmm/quanttradingv2/blob/main/backtest/engine.py) (Backtest Engine), [`main.py`](https://github.com/user-nmmmmm/quanttradingv2/blob/main/main.py) (Backtest CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry_data["Entry and Data"]
  node_backtest_cli["Backtest CLI<br/>[main.py]"]
  node_data_fetcher["Data Fetcher<br/>[data_fetcher.py]"]
  node_market_data["Market Data Adapters<br/>[market_data.py]"]
end

subgraph group_decision["Decision Core"]
  node_event_processor["Event Processor<br/>[runtime.py]"]
  node_state_machine["Market State Machine<br/>[state.py]"]
  node_router["Strategy Router<br/>[router.py]"]
  node_strategies["Trading Strategies<br/>[base.py]"]
  node_allocation["Portfolio Allocation<br/>[allocation.py]"]
  node_risk_manager["Risk Manager<br/>[__init__.py]"]
  node_portfolio["Portfolio and Lots<br/>[portfolio.py]"]
end

subgraph group_execution["Execution"]
  node_backtest_engine["Backtest Engine<br/>[engine.py]"]
  node_live_engine["Live Engine<br/>[engine.py]"]
  node_tick_orchestrator["Tick Orchestrator"]
  node_sim_execution["Simulated Execution"]
  node_broker["Broker Matching<br/>[matching.py]"]
  node_live_broker["Safe Live Broker<br/>[__init__.py]"]
end

subgraph group_operations["Operations"]
  node_state_store[("Durable State<br/>[state_store_v2.py]")]
  node_health["Health and Alerts<br/>[health.py]"]
  node_dashboard["Operations Dashboard<br/>[web.py]"]
end

subgraph group_research["Research and Reporting"]
  node_reporting["Backtest Reporting<br/>[__init__.py]"]
  node_validation["Research Validation"]
  node_signal_analysis["Signal Analysis<br/>[signal_adaptive.py]"]
end

node_backtest_operator(("Backtest Operator"))
node_live_operator(("Live Operator"))
node_market_sources(("Market Data Sources"))
node_exchange(("CCXT Exchange"))
node_dashboard_user(("Dashboard User"))

node_backtest_operator -->|"starts backtest"| node_backtest_cli
node_backtest_cli -->|"requests data"| node_data_fetcher
node_market_sources -->|"supplies prices"| node_data_fetcher
node_data_fetcher -->|"normalizes data"| node_market_data
node_backtest_cli -->|"runs backtest"| node_backtest_engine
node_market_data -->|"delivers bars"| node_event_processor
node_backtest_engine -->|"processes bars"| node_event_processor
node_live_operator -->|"starts polling"| node_live_engine
node_live_engine -->|"runs ticks"| node_tick_orchestrator
node_live_engine -->|"refreshes prices"| node_market_data
node_live_engine -->|"syncs account"| node_live_broker
node_event_processor -->|"checks regime"| node_state_machine
node_event_processor -->|"collects candidates"| node_router
node_router -->|"routes signals"| node_strategies
node_event_processor -->|"allocates candidates"| node_allocation
node_allocation -->|"checks exposure"| node_risk_manager
node_event_processor -->|"checks circuit breaker"| node_risk_manager
node_risk_manager -->|"constrains positions"| node_portfolio
node_event_processor -->|"submits orders"| node_sim_execution
node_sim_execution -->|"adapts execution"| node_broker
node_broker -->|"records fills"| node_portfolio
node_tick_orchestrator -->|"routes bars"| node_event_processor
node_tick_orchestrator -->|"submits orders"| node_live_broker
node_live_broker -->|"places orders"| node_exchange
node_live_engine -->|"persists state"| node_state_store
node_live_engine -->|"assesses health"| node_health
node_backtest_engine -->|"produces reports"| node_reporting
node_backtest_engine -.->|"supports validation"| node_validation
node_backtest_engine -.->|"records signal evidence"| node_signal_analysis
node_dashboard_user -->|"views status"| node_dashboard
node_dashboard -->|"reads operations status"| node_health

click node_backtest_cli "https://github.com/user-nmmmmm/quanttradingv2/blob/main/main.py"
click node_data_fetcher "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/data_fetcher.py"
click node_market_data "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/market_data.py"
click node_backtest_engine "https://github.com/user-nmmmmm/quanttradingv2/blob/main/backtest/engine.py"
click node_live_engine "https://github.com/user-nmmmmm/quanttradingv2/blob/main/live_trading/engine.py"
click node_tick_orchestrator "https://github.com/user-nmmmmm/quanttradingv2/blob/main/live_trading/tick_orchestrator.py"
click node_event_processor "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/runtime.py"
click node_state_machine "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/state.py"
click node_router "https://github.com/user-nmmmmm/quanttradingv2/blob/main/router/router.py"
click node_strategies "https://github.com/user-nmmmmm/quanttradingv2/blob/main/strategies/base.py"
click node_allocation "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/allocation.py"
click node_risk_manager "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/risk/__init__.py"
click node_portfolio "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/portfolio.py"
click node_sim_execution "https://github.com/user-nmmmmm/quanttradingv2/blob/main/backtest/execution_adapter.py"
click node_broker "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/broker/matching.py"
click node_live_broker "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/live_broker/__init__.py"
click node_state_store "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/state_store_v2.py"
click node_health "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/health.py"
click node_dashboard "https://github.com/user-nmmmmm/quanttradingv2/blob/main/dashboard/web.py"
click node_reporting "https://github.com/user-nmmmmm/quanttradingv2/blob/main/backtest/reporting/__init__.py"
click node_validation "https://github.com/user-nmmmmm/quanttradingv2/blob/main/analysis/research_validation.py"
click node_signal_analysis "https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/signal_adaptive.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_backtest_cli,node_data_fetcher,node_market_data,node_dashboard_user toneBlue
class node_event_processor,node_state_machine,node_router,node_strategies,node_allocation,node_risk_manager,node_portfolio toneAmber
class node_backtest_engine,node_live_engine,node_tick_orchestrator,node_sim_execution,node_broker,node_live_broker toneMint
class node_state_store,node_health,node_dashboard toneRose
class node_reporting,node_validation,node_signal_analysis,node_backtest_operator,node_live_operator,node_market_sources,node_exchange toneIndigo
```

## Components

### Entry and Data

- [Backtest CLI](https://github.com/user-nmmmmm/quanttradingv2/blob/main/main.py): `main.py`
- [Data Fetcher](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/data_fetcher.py): `core/data_fetcher.py`
- [Market Data Adapters](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/market_data.py): `core/market_data.py`

### Decision Core

- [Event Processor](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/runtime.py): `core/runtime.py`
- [Market State Machine](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/state.py): `core/state.py`
- [Strategy Router](https://github.com/user-nmmmmm/quanttradingv2/blob/main/router/router.py): `router/router.py`
- [Trading Strategies](https://github.com/user-nmmmmm/quanttradingv2/blob/main/strategies/base.py): `strategies/base.py`
- [Portfolio Allocation](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/allocation.py): `core/allocation.py`
- [Risk Manager](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/risk/__init__.py): `core/risk/__init__.py`
- [Portfolio and Lots](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/portfolio.py): `core/portfolio.py`

### Execution

- [Backtest Engine](https://github.com/user-nmmmmm/quanttradingv2/blob/main/backtest/engine.py): `backtest/engine.py`
- [Live Engine](https://github.com/user-nmmmmm/quanttradingv2/blob/main/live_trading/engine.py): `live_trading/engine.py`
- [Tick Orchestrator](https://github.com/user-nmmmmm/quanttradingv2/blob/main/live_trading/tick_orchestrator.py): `live_trading/tick_orchestrator.py`
- [Simulated Execution](https://github.com/user-nmmmmm/quanttradingv2/blob/main/backtest/execution_adapter.py): `backtest/execution_adapter.py`
- [Broker Matching](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/broker/matching.py): `core/broker/matching.py`
- [Safe Live Broker](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/live_broker/__init__.py): `core/live_broker/__init__.py`

### Operations

- [Durable State](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/state_store_v2.py): `core/state_store_v2.py`
- [Health and Alerts](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/health.py): `core/health.py`
- [Operations Dashboard](https://github.com/user-nmmmmm/quanttradingv2/blob/main/dashboard/web.py): `dashboard/web.py`

### Research and Reporting

- [Backtest Reporting](https://github.com/user-nmmmmm/quanttradingv2/blob/main/backtest/reporting/__init__.py): `backtest/reporting/__init__.py`
- [Research Validation](https://github.com/user-nmmmmm/quanttradingv2/blob/main/analysis/research_validation.py): `analysis/research_validation.py`
- [Signal Analysis](https://github.com/user-nmmmmm/quanttradingv2/blob/main/core/signal_adaptive.py): `core/signal_adaptive.py`

### Other components

- **Backtest Operator**
- **Live Operator**
- **Market Data Sources**
- **CCXT Exchange**
- **Dashboard User**

## Connections

- Backtest Operator → Backtest CLI: starts backtest (evidence: `README.md`)
- Backtest CLI → Data Fetcher: requests data (evidence: `README.md`)
- Market Data Sources → Data Fetcher: supplies prices (evidence: `README.md`)
- Data Fetcher → Market Data Adapters: normalizes data (evidence: `README.md`)
- Backtest CLI → Backtest Engine: runs backtest (evidence: `main.py`)
- Market Data Adapters → Event Processor: delivers bars (evidence: `README.md`)
- Backtest Engine → Event Processor: processes bars (evidence: `README.md`)
- Live Operator → Live Engine: starts polling (evidence: `README.md`)
- Live Engine → Tick Orchestrator: runs ticks (evidence: `live_trading/engine.py`)
- Live Engine → Market Data Adapters: refreshes prices (evidence: `README.md`)
- Live Engine → Safe Live Broker: syncs account (evidence: `README.md`)
- Event Processor → Market State Machine: checks regime (evidence: `README.md`)
- Event Processor → Strategy Router: collects candidates (evidence: `README.md`)
- Strategy Router → Trading Strategies: routes signals (evidence: `router/router.py`)
- Event Processor → Portfolio Allocation: allocates candidates (evidence: `README.md`)
- Portfolio Allocation → Risk Manager: checks exposure (evidence: `README.md`)
- Event Processor → Risk Manager: checks circuit breaker (evidence: `README.md`)
- Risk Manager → Portfolio and Lots: constrains positions (evidence: `README.md`)
- Event Processor → Simulated Execution: submits orders (evidence: `README.md`)
- Simulated Execution → Broker Matching: adapts execution (evidence: `README.md`)
- Broker Matching → Portfolio and Lots: records fills (evidence: `README.md`)
- Tick Orchestrator → Event Processor: routes bars (evidence: `README.md`)
- Tick Orchestrator → Safe Live Broker: submits orders (evidence: `README.md`)
- Safe Live Broker → CCXT Exchange: places orders (evidence: `README.md`)
- Live Engine → Durable State: persists state (evidence: `README.md`)
- Live Engine → Health and Alerts: assesses health (evidence: `README.md`)
- Backtest Engine → Backtest Reporting: produces reports (evidence: `README.md`)
- Backtest Engine → Research Validation: supports validation (evidence: `README.md`)
- Backtest Engine → Signal Analysis: records signal evidence (evidence: `README.md`)
- Dashboard User → Operations Dashboard: views status (evidence: `README.md`)
- Operations Dashboard → Health and Alerts: reads operations status (evidence: `README.md`)
