# alanperry1/forex-bot architecture

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

- Interactive diagram: https://gitdiagram.com/alanperry1/forex-bot
- Repository: https://github.com/alanperry1/forex-bot

## Overview

This is an autonomous OANDA forex-trading bot. Its principal workflow is a recurring bot loop that gathers market and account data, filters and scores trade opportunities across Claude, RandomForest and PPO, sizes and validates a candidate, then executes it and tracks the position. Separate branches provide indicator strategies, model training, alerts and a live dashboard. Relationships follow the README’s documented pipeline and the shown bot/source-index references; several implementation details are unsampled.

Main entry points: [`bot.py`](https://github.com/alanperry1/forex-bot/blob/main/bot.py) (Trading loops), [`data_layer.py`](https://github.com/alanperry1/forex-bot/blob/main/data_layer.py) (Market data client), [`ml/features.py`](https://github.com/alanperry1/forex-bot/blob/main/ml/features.py) (Feature engineering), [`rl/environment.py`](https://github.com/alanperry1/forex-bot/blob/main/rl/environment.py) (Trading environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Trading runtime"]
  node_bot["Trading loops<br/>[bot.py]"]
  node_session["Session filter<br/>[session_filter.py]"]
  node_correlation["Correlation filter"]
  node_news["News blackout<br/>[news.py]"]
  node_gate["Profitability gate"]
end

subgraph group_signals["Signals and models"]
  node_strategy["Indicator strategies<br/>[strategy_engine.py]"]
  node_claude["Claude analysis<br/>[ai_brain.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_rf["RandomForest inference<br/>[predictor.py]"]
  node_mltrain["RF training<br/>[trainer.py]"]
  node_rlagent["PPO inference<br/>[agent.py]"]
  node_rlenv["Trading environment<br/>[environment.py]"]
  node_rlreward["Reward function<br/>[reward.py]"]
  node_rltrain["PPO training<br/>[trainer.py]"]
end

subgraph group_controls["Risk and execution"]
  node_sizing["Consensus sizing"]
  node_risk["Risk validation<br/>[risk_manager.py]"]
  node_executor["Order execution<br/>[executor.py]"]
  node_positions["Position tracking"]
end

subgraph group_operations["Monitoring and records"]
  node_logger[("Trade records<br/>[logger.py]")]
  node_dashboard["Live dashboard<br/>[dashboard.py]"]
  node_alerts["Mobile alerts<br/>[alerts.py]"]
end

subgraph group_integrations["External services"]
  node_market["Market data client<br/>[data_layer.py]"]
  node_anthropic["Anthropic API"]
end

node_operator(("Operator"))
node_oanda["OANDA"]
node_pushover["Pushover"]
node_newsapi["NewsAPI / calendar"]

node_operator -->|"starts"| node_bot
node_bot -->|"requests data"| node_market
node_market -->|"calls REST API"| node_oanda
node_bot -->|"filters by session"| node_session
node_bot -->|"checks pairs"| node_correlation
node_bot -->|"checks blackout"| node_news
node_news -.->|"fetches events"| node_newsapi
node_bot -->|"prechecks trades"| node_gate
node_bot -->|"uses strategies"| node_strategy
node_bot -->|"requests analysis"| node_claude
node_claude -.->|"requests completion"| node_anthropic
node_bot -->|"builds features"| node_features
node_bot -->|"scores trades"| node_rf
node_rf -->|"uses features"| node_features
node_bot -->|"requests signal"| node_rlagent
node_rlagent -.->|"builds observation"| node_features
node_mltrain -->|"uses feature schema"| node_features
node_rltrain -->|"trains on environment"| node_rlenv
node_rlenv -->|"builds observations"| node_features
node_rlenv -.->|"computes reward"| node_rlreward
node_bot -->|"combines consensus"| node_sizing
node_bot -->|"validates trade"| node_risk
node_bot -->|"submits approved order"| node_executor
node_executor -->|"uses broker client"| node_market
node_bot -->|"tracks positions"| node_positions
node_positions -->|"syncs open trades"| node_market
node_bot -->|"records activity"| node_logger
node_dashboard -->|"reads account data"| node_market
node_dashboard -->|"reads session"| node_session
node_bot -->|"sends trade alerts"| node_alerts
node_alerts -.->|"sends notifications"| node_pushover
node_operator -->|"views status"| node_dashboard

click node_bot "https://github.com/alanperry1/forex-bot/blob/main/bot.py"
click node_market "https://github.com/alanperry1/forex-bot/blob/main/data_layer.py"
click node_session "https://github.com/alanperry1/forex-bot/blob/main/session_filter.py"
click node_correlation "https://github.com/alanperry1/forex-bot/blob/main/correlation_filter.py"
click node_news "https://github.com/alanperry1/forex-bot/blob/main/news.py"
click node_gate "https://github.com/alanperry1/forex-bot/blob/main/profitability_gate.py"
click node_strategy "https://github.com/alanperry1/forex-bot/blob/main/strategy_engine.py"
click node_claude "https://github.com/alanperry1/forex-bot/blob/main/ai_brain.py"
click node_features "https://github.com/alanperry1/forex-bot/blob/main/ml/features.py"
click node_rf "https://github.com/alanperry1/forex-bot/blob/main/ml/predictor.py"
click node_mltrain "https://github.com/alanperry1/forex-bot/blob/main/ml/trainer.py"
click node_rlagent "https://github.com/alanperry1/forex-bot/blob/main/rl/agent.py"
click node_rlenv "https://github.com/alanperry1/forex-bot/blob/main/rl/environment.py"
click node_rlreward "https://github.com/alanperry1/forex-bot/blob/main/rl/reward.py"
click node_rltrain "https://github.com/alanperry1/forex-bot/blob/main/rl/trainer.py"
click node_sizing "https://github.com/alanperry1/forex-bot/blob/main/lot_sizing_engine.py"
click node_risk "https://github.com/alanperry1/forex-bot/blob/main/risk_manager.py"
click node_executor "https://github.com/alanperry1/forex-bot/blob/main/executor.py"
click node_positions "https://github.com/alanperry1/forex-bot/blob/main/position_manager.py"
click node_logger "https://github.com/alanperry1/forex-bot/blob/main/logger.py"
click node_dashboard "https://github.com/alanperry1/forex-bot/blob/main/dashboard.py"
click node_alerts "https://github.com/alanperry1/forex-bot/blob/main/alerts.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_bot,node_session,node_correlation,node_news,node_gate toneBlue
class node_strategy,node_claude,node_features,node_rf,node_mltrain,node_rlagent,node_rlenv,node_rlreward,node_rltrain toneAmber
class node_sizing,node_risk,node_executor,node_positions,node_newsapi toneMint
class node_logger,node_dashboard,node_alerts toneRose
class node_market,node_anthropic,node_operator,node_oanda,node_pushover toneIndigo
```

## Components

### Trading runtime

- [Trading loops](https://github.com/alanperry1/forex-bot/blob/main/bot.py): `bot.py`
- [Session filter](https://github.com/alanperry1/forex-bot/blob/main/session_filter.py): `session_filter.py`
- [Correlation filter](https://github.com/alanperry1/forex-bot/blob/main/correlation_filter.py): `correlation_filter.py`
- [News blackout](https://github.com/alanperry1/forex-bot/blob/main/news.py): `news.py`
- [Profitability gate](https://github.com/alanperry1/forex-bot/blob/main/profitability_gate.py): `profitability_gate.py`

### Signals and models

- [Indicator strategies](https://github.com/alanperry1/forex-bot/blob/main/strategy_engine.py): `strategy_engine.py`
- [Claude analysis](https://github.com/alanperry1/forex-bot/blob/main/ai_brain.py): `ai_brain.py`
- [Feature engineering](https://github.com/alanperry1/forex-bot/blob/main/ml/features.py): `ml/features.py`
- [RandomForest inference](https://github.com/alanperry1/forex-bot/blob/main/ml/predictor.py): `ml/predictor.py`
- [RF training](https://github.com/alanperry1/forex-bot/blob/main/ml/trainer.py): `ml/trainer.py`
- [PPO inference](https://github.com/alanperry1/forex-bot/blob/main/rl/agent.py): `rl/agent.py`
- [Trading environment](https://github.com/alanperry1/forex-bot/blob/main/rl/environment.py): `rl/environment.py`
- [Reward function](https://github.com/alanperry1/forex-bot/blob/main/rl/reward.py): `rl/reward.py`
- [PPO training](https://github.com/alanperry1/forex-bot/blob/main/rl/trainer.py): `rl/trainer.py`

### Risk and execution

- [Consensus sizing](https://github.com/alanperry1/forex-bot/blob/main/lot_sizing_engine.py): `lot_sizing_engine.py`
- [Risk validation](https://github.com/alanperry1/forex-bot/blob/main/risk_manager.py): `risk_manager.py`
- [Order execution](https://github.com/alanperry1/forex-bot/blob/main/executor.py): `executor.py`
- [Position tracking](https://github.com/alanperry1/forex-bot/blob/main/position_manager.py): `position_manager.py`

### Monitoring and records

- [Trade records](https://github.com/alanperry1/forex-bot/blob/main/logger.py): `logger.py`
- [Live dashboard](https://github.com/alanperry1/forex-bot/blob/main/dashboard.py): `dashboard.py`
- [Mobile alerts](https://github.com/alanperry1/forex-bot/blob/main/alerts.py): `alerts.py`

### External services

- [Market data client](https://github.com/alanperry1/forex-bot/blob/main/data_layer.py): `data_layer.py`
- **Anthropic API**

### Other components

- **Operator**
- **OANDA**
- **Pushover**
- **NewsAPI / calendar**

## Connections

- Operator → Trading loops: starts (evidence: `README.md`)
- Trading loops → Market data client: requests data (evidence: `bot.py`)
- Market data client → OANDA: calls REST API (evidence: `data_layer.py`)
- Trading loops → Session filter: filters by session (evidence: `README.md`)
- Trading loops → Correlation filter: checks pairs (evidence: `bot.py`)
- Trading loops → News blackout: checks blackout (evidence: `README.md`)
- News blackout → NewsAPI / calendar: fetches events (evidence: `README.md`)
- Trading loops → Profitability gate: prechecks trades (evidence: `README.md`)
- Trading loops → Indicator strategies: uses strategies (evidence: `bot.py`)
- Trading loops → Claude analysis: requests analysis (evidence: `README.md`)
- Claude analysis → Anthropic API: requests completion (evidence: `README.md`)
- Trading loops → Feature engineering: builds features (evidence: `bot.py`)
- Trading loops → RandomForest inference: scores trades (evidence: `bot.py`)
- RandomForest inference → Feature engineering: uses features (evidence: `ml/predictor.py`)
- Trading loops → PPO inference: requests signal (evidence: `bot.py`)
- PPO inference → Feature engineering: builds observation
- RF training → Feature engineering: uses feature schema (evidence: `ml/trainer.py`)
- PPO training → Trading environment: trains on environment (evidence: `rl/trainer.py`)
- Trading environment → Feature engineering: builds observations (evidence: `rl/environment.py`)
- Trading environment → Reward function: computes reward (evidence: `README.md`)
- Trading loops → Consensus sizing: combines consensus (evidence: `bot.py`)
- Trading loops → Risk validation: validates trade (evidence: `README.md`)
- Trading loops → Order execution: submits approved order (evidence: `bot.py`)
- Order execution → Market data client: uses broker client (evidence: `executor.py`)
- Trading loops → Position tracking: tracks positions (evidence: `bot.py`)
- Position tracking → Market data client: syncs open trades (evidence: `position_manager.py`)
- Trading loops → Trade records: records activity (evidence: `bot.py`)
- Live dashboard → Market data client: reads account data (evidence: `dashboard.py`)
- Live dashboard → Session filter: reads session (evidence: `dashboard.py`)
- Trading loops → Mobile alerts: sends trade alerts (evidence: `README.md`)
- Mobile alerts → Pushover: sends notifications (evidence: `README.md`)
- Operator → Live dashboard: views status (evidence: `README.md`)