# aliferous3/gold-bot architecture

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

- Interactive diagram: https://gitdiagram.com/aliferous3/gold-bot
- Repository: https://github.com/aliferous3/gold-bot

## Overview

1. **What this repo is**
   - This is a two-part automated trading system for **MetaTrader 5**: a Python trading/backend layer plus a React/Vite monitoring dashboard.
   - The core responsibility is to schedule breakout trades, place/manage pending orders, monitor triggers and take-profit events, and clean up each trading round safely.

2. **Primary runtime boundary**
   - The main backend boundary is the Python side, centered on `backend/main.py` and likely launched via `app.py` or a direct Uvicorn/FastAPI startup path.
   - The frontend is a separate build/runtime boundary under `frontend/`, compiled by Vite and served as a browser-based dashboard.

3. **Trading engine / round lifecycle**
   - The bot is organized around a **round lifecycle**: schedule → active placement window → pending order activity → trigger detection → TP monitoring → cleanup → repeat/stop.
   - This lifecycle is the architectural core of the system and is what differentiates it from a simple one-shot MT5 script.

4. **MT5 execution boundary**
   - All real trading actions flow through the **MetaTrader5 Python package**.
   - The backend talks directly to MT5 for pending order placement, position queries, history checks, symbol/account data, cancellations, and closing positions.
   - This is the main external integration boundary; there is no separate broker abstraction layer in the current repo structure.

5. **Order placement and retry subsystem**
   - The system places both **Buy Stop** and **Sell Stop** orders with independent offsets, lot sizes, TP, and SL.
   - A key subsystem is the **active placement retry engine**, which keeps retrying missing orders during the configured window, recalculating prices before each attempt and stopping once both orders are present or the window expires.

6. **Trigger detection and cleanup subsystem**
   - Once one side triggers, the bot monitors the resulting positions and the opposite pending order according to the strategy rules described in the README.
   - Cleanup is a separate subsystem that closes remaining positions, cancels remaining pending orders, and finalizes the round when TP is reached or other completion conditions occur.

7. **Duplicate-safety and concurrency controls**
   - The architecture explicitly includes duplicate-prevention mechanisms such as cleanup locks, processed-position tracking, watchdog deduplication, and thread-safe execution.
   - The README also calls out **parallel MT5 execution** for safe concurrent operations like placing the buy/sell orders, closing positions, and canceling pendings, so concurrency is a deliberate design concern rather than an implementation detail.

8. **Backend API / control plane**
   - Because the backend is described as **FastAPI + Pydantic + Uvicorn**, it likely exposes the operational state needed by the dashboard: countdown, round status, event log, configuration, and manual controls.
   - This API layer is the control plane between the web UI and the trading engine, while the engine itself remains the MT5-facing execution layer.

9. **Frontend dashboard**
   - The `frontend/` app is a **React** project built with **Vite** and uses a chart component (`frontend/src/components/GoldChart.jsx`) for live price visualization.
   - The dashboard surfaces operational state rather than trading logic: live chart, countdown timer, breakout settings, round status, event/diagnostic logs, diagnostic download, and manual cancel controls.

10. **Diagnostics and observability**
   - Logging is a first-class subsystem: the bot writes detailed diagnostic logs including timestamps, elapsed time, round number, breakout ID, phase, and thread.
   - The README mentions a downloadable diagnostic log, which implies the backend persists structured operational data that the frontend can expose for review.

11. **Utility scripts and operational tooling**
   - The `scripts/` directory contains targeted maintenance and patch scripts such as cleanup watchdog fixes, TP cleanup changes, order-handling adjustments, and trade-history repair.
   - These scripts are not part of the live trading flow; they represent operational tooling for evolving or repairing strategy behavior and internal state handling.

12. **Test and dry-run surface**
   - Files like `gold_dry_run.py`, `place_test_orders.py`, `test_mt5.py`, and `TEST_LAST_TRADE.md` indicate a separate validation path for MT5 connectivity and strategy behavior.
   - This suggests the repo supports both live execution and isolated sanity checks, which is important for safely testing broker connectivity and order flow.

13. **Likely architectural picture**
   - At a high level, the architecture is:
     - browser dashboard ↔ FastAPI backend ↔ MT5 terminal/API
     - backend also writes diagnostic logs and coordinates round state
     - scripts/tests provide maintenance and validation around the core trading engine
   - The key diagram boundary is between **UI/control**, **trading orchestration**, and **broker execution**.

14. **Where the main complexity lives**
   - The hard parts are not the UI; they are in the backend’s orchestration logic: timing, retries, order state reconciliation, cleanup deduplication, and TP confirmation.
   - If you are drawing an architecture diagram, emphasize the backend as the stateful orchestrator and MT5 as the external execution system.

Main entry points: [`backend/main.py`](https://github.com/aliferous3/gold-bot/blob/main/backend/main.py) (API core), [`gold_bot_v1.py`](https://github.com/aliferous3/gold-bot/blob/main/gold_bot_v1.py) (Trade engine), [`frontend/src/App.jsx`](https://github.com/aliferous3/gold-bot/blob/main/frontend/src/App.jsx) (Dashboard), [`frontend/src/main.jsx`](https://github.com/aliferous3/gold-bot/blob/main/frontend/src/main.jsx) (UI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_app_py["App entry<br/>launcher<br/>[app.py]"]
  node_backend_main["API core<br/>fastapi control plane<br/>[main.py]"]
  node_trade_engine["Trade engine<br/>round orchestrator<br/>[gold_bot_v1.py]"]
  node_oco_monitor["OCO monitor<br/>trigger watcher<br/>[oco_monitor.py]"]
  node_mt5_api[("MT5 terminal<br/>broker runtime")]
end

subgraph group_frontend["Frontend"]
  node_frontend_main["UI entry<br/>vite bootstrap<br/>[main.jsx]"]
  node_dashboard_app["Dashboard<br/>react shell<br/>[App.jsx]"]
  node_gold_chart["Price chart<br/>chart component<br/>[GoldChart.jsx]"]
  node_frontend_readme["UI notes<br/>frontend docs<br/>[README.md]"]
end

subgraph group_ops["Ops"]
  node_scripts_group["Ops scripts<br/>maintenance scripts"]
  node_dry_run["Dry run<br/>sanity check<br/>[gold_dry_run.py]"]
  node_mt5_test["MT5 test<br/>connectivity check<br/>[test_mt5.py]"]
  node_order_test["Order test<br/>test orders"]
  node_log_spec["Trade log<br/>diagnostic notes<br/>[TEST_LAST_TRADE.md]"]
  node_package_lock["Root lockfile<br/>dependency lock<br/>[package-lock.json]"]
end

node_app_py -->|"starts"| node_backend_main
node_backend_main -->|"orchestrates"| node_trade_engine
node_trade_engine -->|"tracks"| node_oco_monitor
node_trade_engine -->|"places/queries"| node_mt5_api
node_oco_monitor -->|"reads/updates"| node_mt5_api
node_backend_main -->|"serves state"| node_frontend_main
node_frontend_main -->|"mounts"| node_dashboard_app
node_dashboard_app -->|"includes"| node_gold_chart
node_dashboard_app -->|"polls/control"| node_backend_main
node_scripts_group -.->|"patches"| node_trade_engine
node_dry_run -.->|"validates"| node_mt5_api
node_mt5_test -.->|"verifies"| node_mt5_api
node_order_test -.->|"exercises"| node_mt5_api
node_log_spec -.->|"documents"| node_backend_main
node_frontend_readme -.->|"documents"| node_dashboard_app
node_package_lock -.->|"supports"| node_frontend_main

click node_app_py "https://github.com/aliferous3/gold-bot/blob/main/app.py"
click node_backend_main "https://github.com/aliferous3/gold-bot/blob/main/backend/main.py"
click node_trade_engine "https://github.com/aliferous3/gold-bot/blob/main/gold_bot_v1.py"
click node_oco_monitor "https://github.com/aliferous3/gold-bot/blob/main/oco_monitor.py"
click node_frontend_main "https://github.com/aliferous3/gold-bot/blob/main/frontend/src/main.jsx"
click node_dashboard_app "https://github.com/aliferous3/gold-bot/blob/main/frontend/src/App.jsx"
click node_gold_chart "https://github.com/aliferous3/gold-bot/blob/main/frontend/src/components/GoldChart.jsx"
click node_scripts_group "https://github.com/aliferous3/gold-bot/blob/main/scripts/apply_entry_adjustment_33.py"
click node_dry_run "https://github.com/aliferous3/gold-bot/blob/main/gold_dry_run.py"
click node_mt5_test "https://github.com/aliferous3/gold-bot/blob/main/test_mt5.py"
click node_order_test "https://github.com/aliferous3/gold-bot/blob/main/place_test_orders.py"
click node_log_spec "https://github.com/aliferous3/gold-bot/blob/main/TEST_LAST_TRADE.md"
click node_frontend_readme "https://github.com/aliferous3/gold-bot/blob/main/frontend/README.md"
click node_package_lock "https://github.com/aliferous3/gold-bot/blob/main/package-lock.json"

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_py,node_backend_main,node_trade_engine,node_oco_monitor,node_mt5_api toneBlue
class node_frontend_main,node_dashboard_app,node_gold_chart,node_frontend_readme toneAmber
class node_scripts_group,node_dry_run,node_mt5_test,node_order_test,node_log_spec,node_package_lock toneMint
```

## Components

### Backend

Python trading backend, orchestration, and MT5 execution

- [App entry](https://github.com/aliferous3/gold-bot/blob/main/app.py): launcher · Top-level startup path for the backend service · `app.py`
- [API core](https://github.com/aliferous3/gold-bot/blob/main/backend/main.py): fastapi control plane · Backend API and operational state surface for the dashboard · `backend/main.py`
- [Trade engine](https://github.com/aliferous3/gold-bot/blob/main/gold_bot_v1.py): round orchestrator · Coordinates breakout rounds, scheduling, retries, and cleanup · `gold_bot_v1.py`
- [OCO monitor](https://github.com/aliferous3/gold-bot/blob/main/oco_monitor.py): trigger watcher · Monitors pending orders, triggers, and opposite-side handling · `oco_monitor.py`
- **MT5 terminal**: broker runtime · External MetaTrader 5 execution boundary for orders, positions, and history

### Frontend

React/Vite dashboard and visualization

- [UI entry](https://github.com/aliferous3/gold-bot/blob/main/frontend/src/main.jsx): vite bootstrap · Frontend bootstrap and application mount · `frontend/src/main.jsx`
- [Dashboard](https://github.com/aliferous3/gold-bot/blob/main/frontend/src/App.jsx): react shell · Main dashboard layout, state views, and controls · `frontend/src/App.jsx`
- [Price chart](https://github.com/aliferous3/gold-bot/blob/main/frontend/src/components/GoldChart.jsx): chart component · Live gold price visualization component · `frontend/src/components/GoldChart.jsx`
- [UI notes](https://github.com/aliferous3/gold-bot/blob/main/frontend/README.md): frontend docs · Frontend-specific build and usage guidance · `frontend/README.md`

### Ops

Maintenance scripts and validation entrypoints

- [Ops scripts](https://github.com/aliferous3/gold-bot/blob/main/scripts/apply_entry_adjustment_33.py): maintenance scripts · Patch and repair scripts for strategy behavior and state fixes · `scripts/apply_entry_adjustment_33.py`
- [Dry run](https://github.com/aliferous3/gold-bot/blob/main/gold_dry_run.py): sanity check · Non-live strategy and MT5 behavior check · `gold_dry_run.py`
- [MT5 test](https://github.com/aliferous3/gold-bot/blob/main/test_mt5.py): connectivity check · Direct MT5 connectivity and order-flow verification · `test_mt5.py`
- [Order test](https://github.com/aliferous3/gold-bot/blob/main/place_test_orders.py): test orders · Test order placement surface for validating execution behavior · `place_test_orders.py`
- [Trade log](https://github.com/aliferous3/gold-bot/blob/main/TEST_LAST_TRADE.md): diagnostic notes · Documented last-trade or diagnostic reference used for troubleshooting · `TEST_LAST_TRADE.md`
- [Root lockfile](https://github.com/aliferous3/gold-bot/blob/main/package-lock.json): dependency lock · Repository-level package lock used for tooling and frontend dependencies · `package-lock.json`

## Connections

- App entry → API core: starts · Launch entry initializes the backend service
- API core → Trade engine: orchestrates · API/control plane delegates trading lifecycle execution
- Trade engine → OCO monitor: tracks · Engine feeds monitor logic for pending orders and trigger state
- Trade engine → MT5 terminal: places/queries · Engine performs all broker actions through MT5
- OCO monitor → MT5 terminal: reads/updates · Monitor inspects positions, pending orders, and history via MT5
- API core → UI entry: serves state · Backend exposes operational state for the dashboard
- UI entry → Dashboard: mounts · Frontend bootstrap renders the application shell
- Dashboard → Price chart: includes · Dashboard embeds live chart visualization
- Dashboard → API core: polls/control · UI consumes round status, logs, and manual controls from backend
- Ops scripts → Trade engine: patches · Operational scripts adjust strategy and cleanup behavior
- Dry run → MT5 terminal: validates · Dry-run path checks execution assumptions against MT5
- MT5 test → MT5 terminal: verifies · Connectivity test exercises the broker boundary
- Order test → MT5 terminal: exercises · Test orders validate pending-order behavior
- Trade log → API core: documents · Diagnostic reference corresponds to backend event logging
- UI notes → Dashboard: documents · Frontend guidance describes the UI runtime and build flow
- Root lockfile → UI entry: supports · Repository tooling and dependency resolution support the frontend build