aliferous3/gold-bot

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.