# zhiwei-3/trading-butler architecture

> Architecture diagram of the GitHub repository zhiwei-3/trading-butler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhiwei-3/trading-butler
- Repository: https://github.com/zhiwei-3/trading-butler

## Overview

Trading Butler is a Telegram-operated MetaTrader 5 trading bot. Its user workflow runs from Telegram commands and callbacks through strategy selection or trading controls, market analysis, signal evaluation, and—when enabled—trade execution; scheduled jobs monitor markets and trade outcomes. Configuration, SQLite persistence, and chart/message helpers support that runtime. The excerpts establish application startup, handler registration, settings, and key package boundaries; several command, evaluator, and execution internals were not sampled, so those workflow links are marked unverified rather than asserted.

Main entry points: [`app.py`](https://github.com/zhiwei-3/trading-butler/blob/main/app.py) (Bot application), [`bot/commands`](https://github.com/zhiwei-3/trading-butler/tree/main/bot/commands) (Bot commands), [`strategies`](https://github.com/zhiwei-3/trading-butler/tree/main/strategies) (Trading strategies), [`bot/jobs`](https://github.com/zhiwei-3/trading-butler/tree/main/bot/jobs) (Scheduled jobs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Telegram interface"]
  node_app["Bot application<br/>[app.py]"]
  node_registry["Handler registry<br/>[registry.py]"]
  node_commands["Bot commands"]
  node_messaging["Telegram messaging<br/>[messaging.py]"]
end

subgraph group_strategy["Strategy and analysis"]
  node_strategy_registry["Strategy registry<br/>[__init__.py]"]
  node_strategy_impl["Trading strategies"]
  node_indicators["Indicators and features<br/>[indicators.py]"]
  node_smc["Market structure analysis<br/>[smc.py]"]
end

subgraph group_trading["Trading runtime"]
  node_backtester["Backtesting<br/>[backtester.py]"]
  node_evaluator["Signal evaluation<br/>[evaluator.py]"]
  node_execution["Order execution<br/>[orders.py]"]
  node_guards["Trade guards"]
  node_mt5["MT5 access<br/>[gateway.py]"]
end

subgraph group_operations["Monitoring and reporting"]
  node_jobs["Scheduled jobs"]
  node_news["News engine<br/>[news_engine.py]"]
  node_charts["Charts and reports"]
end

subgraph group_state["Configuration and state"]
  node_config["Settings and runtime state<br/>[config.py]"]
  node_db_api["Signal persistence API<br/>[signals.py]"]
  node_database[("SQLite persistence<br/>[connection.py]")]
end

node_user(("Telegram user"))

node_user -->|"sends updates"| node_app
node_app -->|"reads credentials"| node_config
node_app -->|"initializes database"| node_database
node_app -->|"initializes MT5"| node_mt5
node_app -->|"installs handlers"| node_registry
node_app -->|"loads registrations"| node_commands
node_registry -->|"dispatches commands"| node_commands
node_commands -.->|"sends replies"| node_messaging
node_commands -.->|"selects strategies"| node_strategy_registry
node_strategy_registry -->|"discovers strategies"| node_strategy_impl
node_strategy_impl -.->|"uses indicators"| node_indicators
node_strategy_impl -.->|"uses structure analysis"| node_smc
node_backtester -->|"loads strategies"| node_strategy_registry
node_backtester -->|"uses analysis"| node_indicators
node_strategy_impl -.->|"packages signals"| node_evaluator
node_evaluator -.->|"records signals"| node_db_api
node_evaluator -.->|"submits intents"| node_execution
node_execution -.->|"checks trade gates"| node_guards
node_execution -->|"routes orders"| node_mt5
node_db_api -->|"persists signals"| node_database
node_app -.->|"starts scheduled jobs"| node_jobs
node_jobs -.->|"monitors news"| node_news
node_jobs -.->|"tracks trades"| node_execution
node_jobs -.->|"generates reports"| node_charts
node_commands -->|"runs optimization"| node_backtester
node_commands -->|"reads journal data"| node_db_api
node_commands -->|"reads account history"| node_mt5

click node_app "https://github.com/zhiwei-3/trading-butler/blob/main/app.py"
click node_registry "https://github.com/zhiwei-3/trading-butler/blob/main/bot/registry.py"
click node_commands "https://github.com/zhiwei-3/trading-butler/tree/main/bot/commands"
click node_messaging "https://github.com/zhiwei-3/trading-butler/blob/main/bot/messaging.py"
click node_strategy_registry "https://github.com/zhiwei-3/trading-butler/blob/main/strategies/__init__.py"
click node_strategy_impl "https://github.com/zhiwei-3/trading-butler/tree/main/strategies"
click node_indicators "https://github.com/zhiwei-3/trading-butler/blob/main/analysis/indicators.py"
click node_smc "https://github.com/zhiwei-3/trading-butler/blob/main/analysis/smc.py"
click node_backtester "https://github.com/zhiwei-3/trading-butler/blob/main/core/backtester.py"
click node_evaluator "https://github.com/zhiwei-3/trading-butler/blob/main/core/evaluator.py"
click node_execution "https://github.com/zhiwei-3/trading-butler/blob/main/core/execution/orders.py"
click node_guards "https://github.com/zhiwei-3/trading-butler/tree/main/core/guards"
click node_mt5 "https://github.com/zhiwei-3/trading-butler/blob/main/core/mt5/gateway.py"
click node_jobs "https://github.com/zhiwei-3/trading-butler/tree/main/bot/jobs"
click node_news "https://github.com/zhiwei-3/trading-butler/blob/main/core/news_engine.py"
click node_charts "https://github.com/zhiwei-3/trading-butler/tree/main/charts"
click node_config "https://github.com/zhiwei-3/trading-butler/blob/main/config.py"
click node_db_api "https://github.com/zhiwei-3/trading-butler/blob/main/core/db/signals.py"
click node_database "https://github.com/zhiwei-3/trading-butler/blob/main/core/db/connection.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_app,node_registry,node_commands,node_messaging,node_user toneBlue
class node_strategy_registry,node_strategy_impl,node_indicators,node_smc toneAmber
class node_backtester,node_evaluator,node_execution,node_guards,node_mt5 toneMint
class node_jobs,node_news,node_charts toneRose
class node_config,node_db_api,node_database toneIndigo
```

## Components

### Telegram interface

- [Bot application](https://github.com/zhiwei-3/trading-butler/blob/main/app.py): `app.py`
- [Handler registry](https://github.com/zhiwei-3/trading-butler/blob/main/bot/registry.py): `bot/registry.py`
- [Bot commands](https://github.com/zhiwei-3/trading-butler/tree/main/bot/commands): `bot/commands`
- [Telegram messaging](https://github.com/zhiwei-3/trading-butler/blob/main/bot/messaging.py): `bot/messaging.py`

### Strategy and analysis

- [Strategy registry](https://github.com/zhiwei-3/trading-butler/blob/main/strategies/__init__.py): `strategies/__init__.py`
- [Trading strategies](https://github.com/zhiwei-3/trading-butler/tree/main/strategies): `strategies`
- [Indicators and features](https://github.com/zhiwei-3/trading-butler/blob/main/analysis/indicators.py): `analysis/indicators.py`
- [Market structure analysis](https://github.com/zhiwei-3/trading-butler/blob/main/analysis/smc.py): `analysis/smc.py`

### Trading runtime

- [Backtesting](https://github.com/zhiwei-3/trading-butler/blob/main/core/backtester.py): `core/backtester.py`
- [Signal evaluation](https://github.com/zhiwei-3/trading-butler/blob/main/core/evaluator.py): `core/evaluator.py`
- [Order execution](https://github.com/zhiwei-3/trading-butler/blob/main/core/execution/orders.py): `core/execution/orders.py`
- [Trade guards](https://github.com/zhiwei-3/trading-butler/tree/main/core/guards): `core/guards`
- [MT5 access](https://github.com/zhiwei-3/trading-butler/blob/main/core/mt5/gateway.py): `core/mt5/gateway.py`

### Monitoring and reporting

- [Scheduled jobs](https://github.com/zhiwei-3/trading-butler/tree/main/bot/jobs): `bot/jobs`
- [News engine](https://github.com/zhiwei-3/trading-butler/blob/main/core/news_engine.py): `core/news_engine.py`
- [Charts and reports](https://github.com/zhiwei-3/trading-butler/tree/main/charts): `charts`

### Configuration and state

- [Settings and runtime state](https://github.com/zhiwei-3/trading-butler/blob/main/config.py): `config.py`
- [Signal persistence API](https://github.com/zhiwei-3/trading-butler/blob/main/core/db/signals.py): `core/db/signals.py`
- [SQLite persistence](https://github.com/zhiwei-3/trading-butler/blob/main/core/db/connection.py): `core/db/connection.py`

### Other components

- **Telegram user**

## Connections

- Telegram user → Bot application: sends updates (evidence: `app.py`)
- Bot application → Settings and runtime state: reads credentials (evidence: `app.py`)
- Bot application → SQLite persistence: initializes database (evidence: `app.py`)
- Bot application → MT5 access: initializes MT5 (evidence: `app.py`)
- Bot application → Handler registry: installs handlers (evidence: `app.py`)
- Bot application → Bot commands: loads registrations (evidence: `app.py`)
- Handler registry → Bot commands: dispatches commands (evidence: `bot/registry.py`)
- Bot commands → Telegram messaging: sends replies (evidence: `bot/commands/journal.py`)
- Bot commands → Strategy registry: selects strategies (evidence: `bot/commands/optimize.py`)
- Strategy registry → Trading strategies: discovers strategies (evidence: `strategies/__init__.py`)
- Trading strategies → Indicators and features: uses indicators
- Trading strategies → Market structure analysis: uses structure analysis
- Backtesting → Strategy registry: loads strategies (evidence: `core/backtester.py`)
- Backtesting → Indicators and features: uses analysis (evidence: `core/backtester.py`)
- Trading strategies → Signal evaluation: packages signals
- Signal evaluation → Signal persistence API: records signals
- Signal evaluation → Order execution: submits intents
- Order execution → Trade guards: checks trade gates
- Order execution → MT5 access: routes orders (evidence: `core/execution/orders.py`)
- Signal persistence API → SQLite persistence: persists signals (evidence: `core/db/signals.py`)
- Bot application → Scheduled jobs: starts scheduled jobs (evidence: `app.py`)
- Scheduled jobs → News engine: monitors news
- Scheduled jobs → Order execution: tracks trades
- Scheduled jobs → Charts and reports: generates reports (evidence: `bot/jobs/tracker.py`)
- Bot commands → Backtesting: runs optimization (evidence: `bot/commands/optimize.py`)
- Bot commands → Signal persistence API: reads journal data (evidence: `bot/commands/journal.py`)
- Bot commands → MT5 access: reads account history (evidence: `bot/commands/journal.py`)
