# zero-was-here/tradingbot architecture

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

- Interactive diagram: https://gitdiagram.com/zero-was-here/tradingbot
- Repository: https://github.com/zero-was-here/tradingbot

## Overview

This repository is an XAUUSD deep-reinforcement-learning trading system. Its main workflow gathers market and event data, builds multi-timeframe and macro features, trains or evaluates a policy in a trading environment, then uses live adapters for broker execution. The README also describes risk controls, backtesting, sentiment, and production monitoring. Some subsystems are documented but their wiring is not visible in the sampled source, so uncertain call relationships are omitted.

Main entry points: [`features/god_mode_features.py`](https://github.com/zero-was-here/tradingbot/blob/main/features/god_mode_features.py) (Multi-source features), [`live_trade_mt5.py`](https://github.com/zero-was-here/tradingbot/blob/main/live_trade_mt5.py) (MT5 live adapter), [`live_trade_metaapi.py`](https://github.com/zero-was-here/tradingbot/blob/main/live_trade_metaapi.py) (MetaAPI live adapter), [`train/train_dreamer.py`](https://github.com/zero-was-here/tradingbot/blob/main/train/train_dreamer.py) (Dreamer training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market_data["Market data"]
  node_market_load["Market data loading<br/>[load_data.py]"]
  node_macro_fetch["Macro data fetching"]
  node_macro_merge["Macro data merging<br/>[merge_macro.py]"]
  node_sentiment["Sentiment analysis"]
  node_calendar["Economic calendar"]
end

subgraph group_intelligence["Features and policy"]
  node_feature_build["Feature engineering<br/>[make_features.py]"]
  node_god_features["Multi-source features"]
  node_macro_features["Macro features<br/>[macro_features.py]"]
  node_dreamer["Dreamer agent<br/>[dreamer_agent.py]"]
  node_ppo["PPO policy<br/>[train_ppo.py]"]
  node_risk["Position and risk controls<br/>[risk_supervisor.py]"]
end

subgraph group_simulation["Simulation and validation"]
  node_env["Trading environment<br/>[xauusd_env.py]"]
  node_execution_costs["Execution cost model"]
  node_training["Dreamer training<br/>[train_dreamer.py]"]
  node_backtest["Backtesting<br/>[backtest_engine.py]"]
  node_evaluation["Model evaluation<br/>[evaluate_model.py]"]
  node_crisis["Crisis validation"]
end

subgraph group_operations["Live operations"]
  node_mt5["MT5 live adapter<br/>[live_trade_mt5.py]"]
  node_metaapi["MetaAPI live adapter"]
  node_monitor["Production monitoring"]
end

node_operator(("Trader / operator"))
node_price_sources(("Market data sources"))
node_broker(("Trading broker"))

node_operator -->|"starts training"| node_training
node_operator -->|"requests evaluation"| node_evaluation
node_operator -->|"starts live trading"| node_mt5
node_operator -.->|"starts live trading"| node_metaapi
node_price_sources -->|"provides prices"| node_market_load
node_price_sources -->|"provides macro data"| node_macro_fetch
node_market_load -->|"supplies market data"| node_feature_build
node_macro_fetch -->|"supplies macro data"| node_macro_merge
node_macro_merge -->|"supplies merged data"| node_macro_features
node_sentiment -.->|"provides sentiment"| node_feature_build
node_calendar -->|"provides event features"| node_god_features
node_feature_build -->|"builds feature set"| node_god_features
node_macro_features -->|"adds macro signals"| node_god_features
node_god_features -->|"supplies training features"| node_training
node_training -->|"trains through"| node_env
node_training -->|"updates agent"| node_dreamer
node_ppo -->|"trains through"| node_env
node_backtest -->|"simulates trades"| node_env
node_env -->|"models fill costs"| node_execution_costs
node_evaluation -->|"loads feature set"| node_god_features
node_evaluation -->|"evaluates agent"| node_dreamer
node_crisis -->|"tests agent"| node_dreamer
node_mt5 -->|"sends orders"| node_broker
node_metaapi -.->|"sends orders"| node_broker
node_mt5 -->|"applies risk controls"| node_risk
node_metaapi -.->|"applies risk controls"| node_risk
node_mt5 -->|"reports live state"| node_monitor
node_metaapi -.->|"reports live state"| node_monitor

click node_market_load "https://github.com/zero-was-here/tradingbot/blob/main/data/load_data.py"
click node_macro_fetch "https://github.com/zero-was-here/tradingbot/blob/main/data/fetch_correlations.py"
click node_macro_merge "https://github.com/zero-was-here/tradingbot/blob/main/data/merge_macro.py"
click node_sentiment "https://github.com/zero-was-here/tradingbot/blob/main/data/sentiment_analysis.py"
click node_calendar "https://github.com/zero-was-here/tradingbot/blob/main/data/economic_calendar.py"
click node_feature_build "https://github.com/zero-was-here/tradingbot/blob/main/features/make_features.py"
click node_god_features "https://github.com/zero-was-here/tradingbot/blob/main/features/god_mode_features.py"
click node_macro_features "https://github.com/zero-was-here/tradingbot/blob/main/features/macro_features.py"
click node_dreamer "https://github.com/zero-was-here/tradingbot/blob/main/models/dreamer_agent.py"
click node_ppo "https://github.com/zero-was-here/tradingbot/blob/main/train/train_ppo.py"
click node_risk "https://github.com/zero-was-here/tradingbot/blob/main/models/risk_supervisor.py"
click node_env "https://github.com/zero-was-here/tradingbot/blob/main/env/xauusd_env.py"
click node_execution_costs "https://github.com/zero-was-here/tradingbot/blob/main/env/realistic_execution.py"
click node_training "https://github.com/zero-was-here/tradingbot/blob/main/train/train_dreamer.py"
click node_backtest "https://github.com/zero-was-here/tradingbot/blob/main/backtest/backtest_engine.py"
click node_evaluation "https://github.com/zero-was-here/tradingbot/blob/main/evaluate_model.py"
click node_crisis "https://github.com/zero-was-here/tradingbot/blob/main/eval/crisis_validation.py"
click node_mt5 "https://github.com/zero-was-here/tradingbot/blob/main/live_trade_mt5.py"
click node_metaapi "https://github.com/zero-was-here/tradingbot/blob/main/live_trade_metaapi.py"
click node_monitor "https://github.com/zero-was-here/tradingbot/blob/main/monitoring/production_monitor.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_market_load,node_macro_fetch,node_macro_merge,node_sentiment,node_calendar toneBlue
class node_feature_build,node_god_features,node_macro_features,node_dreamer,node_ppo,node_risk toneAmber
class node_env,node_execution_costs,node_training,node_backtest,node_evaluation,node_crisis toneMint
class node_mt5,node_metaapi,node_monitor toneRose
class node_operator,node_price_sources,node_broker toneIndigo
```

## Components

### Market data

- [Market data loading](https://github.com/zero-was-here/tradingbot/blob/main/data/load_data.py): `data/load_data.py`
- [Macro data fetching](https://github.com/zero-was-here/tradingbot/blob/main/data/fetch_correlations.py): `data/fetch_correlations.py`
- [Macro data merging](https://github.com/zero-was-here/tradingbot/blob/main/data/merge_macro.py): `data/merge_macro.py`
- [Sentiment analysis](https://github.com/zero-was-here/tradingbot/blob/main/data/sentiment_analysis.py): `data/sentiment_analysis.py`
- [Economic calendar](https://github.com/zero-was-here/tradingbot/blob/main/data/economic_calendar.py): `data/economic_calendar.py`

### Features and policy

- [Feature engineering](https://github.com/zero-was-here/tradingbot/blob/main/features/make_features.py): `features/make_features.py`
- [Multi-source features](https://github.com/zero-was-here/tradingbot/blob/main/features/god_mode_features.py): `features/god_mode_features.py`
- [Macro features](https://github.com/zero-was-here/tradingbot/blob/main/features/macro_features.py): `features/macro_features.py`
- [Dreamer agent](https://github.com/zero-was-here/tradingbot/blob/main/models/dreamer_agent.py): `models/dreamer_agent.py`
- [PPO policy](https://github.com/zero-was-here/tradingbot/blob/main/train/train_ppo.py): `train/train_ppo.py`
- [Position and risk controls](https://github.com/zero-was-here/tradingbot/blob/main/models/risk_supervisor.py): `models/risk_supervisor.py`

### Simulation and validation

- [Trading environment](https://github.com/zero-was-here/tradingbot/blob/main/env/xauusd_env.py): `env/xauusd_env.py`
- [Execution cost model](https://github.com/zero-was-here/tradingbot/blob/main/env/realistic_execution.py): `env/realistic_execution.py`
- [Dreamer training](https://github.com/zero-was-here/tradingbot/blob/main/train/train_dreamer.py): `train/train_dreamer.py`
- [Backtesting](https://github.com/zero-was-here/tradingbot/blob/main/backtest/backtest_engine.py): `backtest/backtest_engine.py`
- [Model evaluation](https://github.com/zero-was-here/tradingbot/blob/main/evaluate_model.py): `evaluate_model.py`
- [Crisis validation](https://github.com/zero-was-here/tradingbot/blob/main/eval/crisis_validation.py): `eval/crisis_validation.py`

### Live operations

- [MT5 live adapter](https://github.com/zero-was-here/tradingbot/blob/main/live_trade_mt5.py): `live_trade_mt5.py`
- [MetaAPI live adapter](https://github.com/zero-was-here/tradingbot/blob/main/live_trade_metaapi.py): `live_trade_metaapi.py`
- [Production monitoring](https://github.com/zero-was-here/tradingbot/blob/main/monitoring/production_monitor.py): `monitoring/production_monitor.py`

### Other components

- **Trader / operator**
- **Market data sources**
- **Trading broker**

## Connections

- Trader / operator → Dreamer training: starts training
- Trader / operator → Model evaluation: requests evaluation
- Trader / operator → MT5 live adapter: starts live trading
- Trader / operator → MetaAPI live adapter: starts live trading
- Market data sources → Market data loading: provides prices
- Market data sources → Macro data fetching: provides macro data
- Market data loading → Feature engineering: supplies market data
- Macro data fetching → Macro data merging: supplies macro data
- Macro data merging → Macro features: supplies merged data
- Sentiment analysis → Feature engineering: provides sentiment
- Economic calendar → Multi-source features: provides event features
- Feature engineering → Multi-source features: builds feature set
- Macro features → Multi-source features: adds macro signals
- Multi-source features → Dreamer training: supplies training features
- Dreamer training → Trading environment: trains through
- Dreamer training → Dreamer agent: updates agent
- PPO policy → Trading environment: trains through
- Backtesting → Trading environment: simulates trades
- Trading environment → Execution cost model: models fill costs
- Model evaluation → Multi-source features: loads feature set
- Model evaluation → Dreamer agent: evaluates agent
- Crisis validation → Dreamer agent: tests agent
- MT5 live adapter → Trading broker: sends orders
- MetaAPI live adapter → Trading broker: sends orders
- MT5 live adapter → Position and risk controls: applies risk controls
- MetaAPI live adapter → Position and risk controls: applies risk controls
- MT5 live adapter → Production monitoring: reports live state
- MetaAPI live adapter → Production monitoring: reports live state