# ethanalgox/llm-tradebot architecture

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

- Interactive diagram: https://gitdiagram.com/ethanalgox/llm-tradebot
- Repository: https://github.com/ethanalgox/llm-tradebot

## Overview

1. **What this repo is**
   - A Python 3.11+ automated crypto futures trading system centered on an **adversarial multi-agent decision pipeline**.
   - It has three operational surfaces: **live/test trading**, **backtesting/research**, and a **browser dashboard**.

2. **Primary entrypoints**
   - `main.py` runs the full trading system and the dashboard-backed live/test loop.
   - `simple_cli.py` is a lean headless runtime for production-style trading without the web UI.
   - `backtest.py` and the `research/` package run historical simulation, comparison, and optimization workflows.
   - `src/server/app.py` plus `web/` provide the dashboard/backend boundary.

3. **Cycle orchestration**
   - The heart of the system is in `src/runners/`, which composes a per-cycle pipeline:
     - data sync
     - analysis
     - decision
     - risk audit
     - execution
   - `cycle_pipeline_runner.py` and the stage runners formalize this flow so live trading and backtesting can share the same logical stages.

4. **Market-data ingestion and snapshot alignment**
   - `src/api/` contains exchange data clients and websocket support.
   - `DataSyncAgent` and helpers in `src/utils/` align **multi-timeframe snapshots**, especially 5m/15m/1h data.
   - This alignment is a key architectural boundary: downstream agents consume a single synchronized snapshot rather than independent time series.

5. **Feature and validation layer**
   - `src/data/` validates and processes raw market inputs.
   - `src/features/` builds technical features from the aligned snapshot.
   - `src/utils/data_alignment.py`, `kline_cache.py`, and related helpers support consistency, caching, and auditability of the raw-to-feature transformation.

6. **Multi-agent analysis layer**
   - `src/agents/` is the main intelligence subsystem.
   - Core always-on agents:
     - `data_sync`
     - `quant_analyst`
     - `decision_core`
     - `risk_audit`
   - Optional agents add specialized views: symbol selection, regime detection, position analysis, trigger detection, prediction, reflection, and trend/setup/trigger semantic analysis.
   - Many agents have both **LLM** and **local/rule-based** variants, which is an important runtime boundary.

7. **Decision framework**
   - The repo’s central logic is the **Adversarial Decision Framework**:
     - quantitative signals
     - semantic analysis
     - optional prediction/filtering
     - multi-period summary
     - final vote aggregation in `DecisionCoreAgent`
   - Files like `overtrading_guard.py`, `signal_weight.py`, `vote_result.py`, and `trade_record.py` show that the system is explicitly modeling confidence, vetoes, and trade history, not just issuing raw buy/sell signals.

8. **Risk and execution boundary**
   - `src/risk/manager.py` and `src/agents/risk_audit/` provide a hard safety layer before orders are sent.
   - `src/execution/engine.py` is the handoff point from “decision” to “order placed.”
   - `src/exchanges/` abstracts the broker/exchange side; Binance futures is the implemented target via `binance_trader.py`, with multi-account management in `account_manager.py`.

9. **LLM integration boundary**
   - `src/llm/` is a provider abstraction layer with clients for DeepSeek, OpenAI, Claude, Qwen, Gemini, MiniMax, GLM, OpenRouter, and Kimi.
   - `factory.py` centralizes provider selection, so the rest of the system is insulated from vendor-specific APIs.
   - Prompt templates and agent-specific prompt/config handling live in `src/config/` and agent setup modules.

10. **Machine-learning and strategy support**
   - `src/models/prophet_model.py` and `src/agents/predict/` implement the prediction side, including a LightGBM-based probability model described in the README.
   - `src/strategy/` and `src/strategies/` hold lower-level decision/indicator logic that can be composed into the agent pipeline.

11. **Backtesting and research**
   - `src/backtest/` mirrors the trading pipeline for simulation: replay, portfolio accounting, metrics, analytics, reporting, and storage.
   - `research/` contains exploratory workflows and strategy comparison tools.
   - The README indicates the backtest path is intended to stay behaviorally aligned with live trading, including risk audit and multi-layer filtering.

12. **Observability, state, and persistence**
   - Runtime state is persisted under `data/` in separate folders for market data, indicators, features, decisions, and execution records.
   - `src/monitoring/`, `src/utils/logger.py`, `pipeline_logger.py`, and `trade_logger.py` handle runtime logging and audit trails.
   - This makes the system **white-box**: every cycle leaves a trace from raw candles to final order action.

13. **User-facing interface**
   - `web/` contains the dashboard frontend assets, while `src/server/` provides the application state/config backend.
   - The dashboard is not just cosmetic; it exposes agent outputs, configuration, mode switching, and historical traces, so it sits directly on top of the trading pipeline.

14. **Operational and test boundaries**
   - `config.example.yaml`, `.env.example`, and `config/accounts.example.json` define the main configuration surface.
   - `tests/` covers protocols, agents, risk, execution, data flow, and backtest behavior, which suggests the repo is organized around contract-style boundaries between subsystems.
   - Docker and shell scripts (`Dockerfile`, `docker/`, `start.sh`, `install.sh`, `scripts/`) support deployment, migration, and validation, but they do not change the core architecture.

Main entry points: [`src/runners`](https://github.com/ethanalgox/llm-tradebot/tree/main/src/runners) (Cycle Runners), [`src/agents/data_sync/data_sync_agent.py`](https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/data_sync/data_sync_agent.py) (Data Sync Agent), [`src/execution/engine.py`](https://github.com/ethanalgox/llm-tradebot/blob/main/src/execution/engine.py) (Execution Engine), [`src/backtest`](https://github.com/ethanalgox/llm-tradebot/tree/main/src/backtest) (Backtest Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entrypoints["Entrypoints"]
  node_main_py["main.py<br/>runtime entrypoint<br/>[main.py]"]
  node_simple_cli_py["simple_cli.py<br/>cli entrypoint<br/>[simple_cli.py]"]
  node_backtest_py["backtest.py<br/>simulation entrypoint<br/>[backtest.py]"]
end

subgraph group_core["Trading Core"]
  node_src_runners["Cycle Runners<br/>pipeline orchestration"]
  node_src_trading["Trading Bot<br/>cycle runtime"]
end

subgraph group_intelligence["Agent Intelligence"]
  node_src_agents_sync["Data Sync Agent<br/>[data_sync_agent.py]"]
  node_src_agents_quant["Quant Analyst<br/>agent"]
  node_src_agents_decision_core["Decision Core<br/>adversarial voter"]
  node_src_agents_risk_audit["Risk Audit<br/>safety agent"]
  node_src_agents_optional["Specialist Agents<br/>semantic agents"]
end

subgraph group_infra["Infrastructure"]
  node_src_api["Market API<br/>exchange data clients"]
  node_src_data["Data Validation<br/>market data processing"]
  node_src_features["Feature Builder<br/>technical features"]
  node_src_utils_alignment["Snapshot Alignment<br/>data alignment utilities<br/>[data_alignment.py]"]
  node_src_llm["LLM Layer<br/>provider abstraction"]
  node_src_risk["Risk Manager<br/>risk controls<br/>[manager.py]"]
  node_src_execution["Execution Engine<br/>order handoff<br/>[engine.py]"]
  node_src_exchanges["Exchange Layer<br/>broker adapter"]
  node_src_server_web["Dashboard<br/>ui/backend boundary<br/>[app.py]"]
end

subgraph group_research["Research"]
  node_src_backtest["Backtest Engine<br/>simulation core"]
  node_research_pkg["Research Tools<br/>exploration workflows"]
end

node_main_py -->|"starts"| node_src_runners
node_simple_cli_py -->|"starts"| node_src_trading
node_backtest_py -->|"runs"| node_src_backtest
node_src_trading -->|"uses"| node_src_runners
node_src_runners -->|"stage 1"| node_src_agents_sync
node_src_runners -->|"stage 2"| node_src_agents_quant
node_src_runners -->|"stage 3"| node_src_agents_decision_core
node_src_runners -->|"stage 4"| node_src_agents_risk_audit
node_src_runners -->|"stage 5"| node_src_execution
node_src_agents_sync -->|"ingests"| node_src_api
node_src_agents_sync -->|"aligns"| node_src_utils_alignment
node_src_agents_sync -->|"validates"| node_src_data
node_src_data -->|"feeds"| node_src_features
node_src_features -->|"signals"| node_src_agents_quant
node_src_agents_optional -->|"specializes"| node_src_agents_decision_core
node_src_llm -->|"powers"| node_src_agents_optional
node_src_agents_risk_audit -->|"enforces"| node_src_risk
node_src_risk -->|"gates"| node_src_execution
node_src_execution -->|"routes orders"| node_src_exchanges
node_src_exchanges -->|"targets"| node_src_api
node_src_runners -->|"mirrors"| node_src_backtest
node_research_pkg -->|"analyzes"| node_src_backtest
node_main_py -->|"serves"| node_src_server_web

click node_main_py "https://github.com/ethanalgox/llm-tradebot/blob/main/main.py"
click node_simple_cli_py "https://github.com/ethanalgox/llm-tradebot/blob/main/simple_cli.py"
click node_backtest_py "https://github.com/ethanalgox/llm-tradebot/blob/main/backtest.py"
click node_src_runners "https://github.com/ethanalgox/llm-tradebot/tree/main/src/runners"
click node_src_trading "https://github.com/ethanalgox/llm-tradebot/tree/main/src/trading"
click node_src_api "https://github.com/ethanalgox/llm-tradebot/tree/main/src/api"
click node_src_data "https://github.com/ethanalgox/llm-tradebot/tree/main/src/data"
click node_src_features "https://github.com/ethanalgox/llm-tradebot/tree/main/src/features"
click node_src_utils_alignment "https://github.com/ethanalgox/llm-tradebot/blob/main/src/utils/data_alignment.py"
click node_src_agents_sync "https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/data_sync/data_sync_agent.py"
click node_src_agents_quant "https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/quant_analyst_agent.py"
click node_src_agents_decision_core "https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/decision_core/decision_core_agent.py"
click node_src_agents_risk_audit "https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/risk_audit/risk_audit_agent.py"
click node_src_agents_optional "https://github.com/ethanalgox/llm-tradebot/tree/main/src/agents"
click node_src_llm "https://github.com/ethanalgox/llm-tradebot/tree/main/src/llm"
click node_src_risk "https://github.com/ethanalgox/llm-tradebot/blob/main/src/risk/manager.py"
click node_src_execution "https://github.com/ethanalgox/llm-tradebot/blob/main/src/execution/engine.py"
click node_src_exchanges "https://github.com/ethanalgox/llm-tradebot/tree/main/src/exchanges"
click node_src_backtest "https://github.com/ethanalgox/llm-tradebot/tree/main/src/backtest"
click node_research_pkg "https://github.com/ethanalgox/llm-tradebot/tree/main/research"
click node_src_server_web "https://github.com/ethanalgox/llm-tradebot/blob/main/src/server/app.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_main_py,node_simple_cli_py,node_backtest_py toneBlue
class node_src_runners,node_src_trading toneAmber
class node_src_agents_sync,node_src_agents_quant,node_src_agents_decision_core,node_src_agents_risk_audit,node_src_agents_optional toneMint
class node_src_api,node_src_data,node_src_features,node_src_utils_alignment,node_src_llm,node_src_risk,node_src_execution,node_src_exchanges,node_src_server_web toneRose
class node_src_backtest,node_research_pkg toneIndigo
```

## Components

### Entrypoints

Primary runtime and workflow entry scripts

- [main.py](https://github.com/ethanalgox/llm-tradebot/blob/main/main.py): runtime entrypoint · Full trading system entrypoint with dashboard-backed live/test loop · `main.py`
- [simple_cli.py](https://github.com/ethanalgox/llm-tradebot/blob/main/simple_cli.py): cli entrypoint · Headless production-style trading runtime · `simple_cli.py`
- [backtest.py](https://github.com/ethanalgox/llm-tradebot/blob/main/backtest.py): simulation entrypoint · Standalone backtesting entrypoint · `backtest.py`

### Trading Core

Live trading pipeline and orchestration

- [Cycle Runners](https://github.com/ethanalgox/llm-tradebot/tree/main/src/runners): pipeline orchestration · Composes the per-cycle stages for live trading and backtesting · `src/runners`
- [Trading Bot](https://github.com/ethanalgox/llm-tradebot/tree/main/src/trading): cycle runtime · Coordinates symbol context, filters, and multi-agent trading flow · `src/trading`

### Agent Intelligence

Multi-agent analysis and decision layers

- [Data Sync Agent](https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/data_sync/data_sync_agent.py): agent · Creates synchronized snapshots for downstream analysis · `src/agents/data_sync/data_sync_agent.py`
- [Quant Analyst](https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/quant_analyst_agent.py): agent · Produces quantitative signals and analysis · `src/agents/quant_analyst_agent.py`
- [Decision Core](https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/decision_core/decision_core_agent.py): adversarial voter · Aggregates votes, confidence, vetoes, and trade history into final decisions · `src/agents/decision_core/decision_core_agent.py`
- [Risk Audit](https://github.com/ethanalgox/llm-tradebot/blob/main/src/agents/risk_audit/risk_audit_agent.py): safety agent · Hard safety gate before execution · `src/agents/risk_audit/risk_audit_agent.py`
- [Specialist Agents](https://github.com/ethanalgox/llm-tradebot/tree/main/src/agents): semantic agents · Optional symbol, regime, setup, trend, trigger, reflection, and prediction agents · `src/agents`

### Infrastructure

Exchange, risk, LLM, storage, and server boundaries

- [Market API](https://github.com/ethanalgox/llm-tradebot/tree/main/src/api): exchange data clients · Exchange clients and websocket ingestion · `src/api`
- [Data Validation](https://github.com/ethanalgox/llm-tradebot/tree/main/src/data): market data processing · Validates and normalizes raw market inputs · `src/data`
- [Feature Builder](https://github.com/ethanalgox/llm-tradebot/tree/main/src/features): technical features · Builds technical features from aligned snapshots · `src/features`
- [Snapshot Alignment](https://github.com/ethanalgox/llm-tradebot/blob/main/src/utils/data_alignment.py): data alignment utilities · Aligns multi-timeframe snapshots and supports cache/audit consistency · `src/utils/data_alignment.py`
- [LLM Layer](https://github.com/ethanalgox/llm-tradebot/tree/main/src/llm): provider abstraction · Vendor-neutral client and factory layer for model providers · `src/llm`
- [Risk Manager](https://github.com/ethanalgox/llm-tradebot/blob/main/src/risk/manager.py): risk controls · System-level risk constraints and pre-order checks · `src/risk/manager.py`
- [Execution Engine](https://github.com/ethanalgox/llm-tradebot/blob/main/src/execution/engine.py): order handoff · Bridges approved decisions into exchange orders · `src/execution/engine.py`
- [Exchange Layer](https://github.com/ethanalgox/llm-tradebot/tree/main/src/exchanges): broker adapter · Broker abstraction with Binance futures implementation and account management · `src/exchanges`
- [Dashboard](https://github.com/ethanalgox/llm-tradebot/blob/main/src/server/app.py): ui/backend boundary · Server state/config backend and browser dashboard frontend · `src/server/app.py`

### Research

Backtest and exploratory analysis workflows

- [Backtest Engine](https://github.com/ethanalgox/llm-tradebot/tree/main/src/backtest): simulation core · Replay, accounting, metrics, reporting, and storage for simulation · `src/backtest`
- [Research Tools](https://github.com/ethanalgox/llm-tradebot/tree/main/research): exploration workflows · Strategy comparison and exploratory research workflows · `research`

## Connections

- main.py → Cycle Runners: starts · Main runtime enters the shared cycle pipeline
- simple_cli.py → Trading Bot: starts · Headless runtime drives the trading bot
- backtest.py → Backtest Engine: runs · Standalone backtest entrypoint invokes simulation engine
- Trading Bot → Cycle Runners: uses · Trading bot relies on shared stage runners
- Cycle Runners → Data Sync Agent: stage 1 · Per-cycle data sync and snapshot creation
- Cycle Runners → Quant Analyst: stage 2 · Quantitative analysis stage
- Cycle Runners → Decision Core: stage 3 · Final vote aggregation and decisioning
- Cycle Runners → Risk Audit: stage 4 · Risk audit gate before execution
- Cycle Runners → Execution Engine: stage 5 · Execution handoff after approval
- Data Sync Agent → Market API: ingests · Pulls exchange data and websocket updates
- Data Sync Agent → Snapshot Alignment: aligns · Builds synchronized multi-timeframe snapshots
- Data Sync Agent → Data Validation: validates · Routes raw market inputs through validation layer
- Data Validation → Feature Builder: feeds · Validated data becomes feature inputs
- Feature Builder → Quant Analyst: signals · Technical features power quant analysis
- Specialist Agents → Decision Core: specializes · Specialist agents feed semantic and predictive views into the decision core
- LLM Layer → Specialist Agents: powers · LLM-backed variants use provider abstraction
- Risk Audit → Risk Manager: enforces · Agent-level safety checks defer to system risk manager
- Risk Manager → Execution Engine: gates · Risk manager can block or constrain order placement
- Execution Engine → Exchange Layer: routes orders · Execution engine submits orders through exchange adapters
- Exchange Layer → Market API: targets · Broker adapter depends on exchange client surface
- Cycle Runners → Backtest Engine: mirrors · Backtest reuses the live cycle structure
- Research Tools → Backtest Engine: analyzes · Research workflows use backtest engine and comparisons
- main.py → Dashboard: serves · Main runtime exposes dashboard-backed control and state