# jonusnattapong/reinforcement-learning-for-gold-trading architecture

> Architecture diagram of the GitHub repository jonusnattapong/reinforcement-learning-for-gold-trading, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jonusnattapong/reinforcement-learning-for-gold-trading
- Repository: https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading

## Overview

This repository trains and evaluates PPO agents for XAUUSD trading. The user starts a train, evaluation, or combined run; the runner loads and prepares price history, builds training and evaluation environments, and coordinates learning and validation/testing. The trading environment simulates positions, costs, rewards, and risk limits; evaluation reports daily profit, win rate, drawdown, Sharpe ratio, and trades. README capabilities also include CSV or Hugging Face data, configurable settings, and loading a pretrained model. Edges follow sampled calls, SOURCE INDEX references, or README statements; unsampled implementation details are not inferred.

Main entry points: [`src/rl_gold_trading/run.py`](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/run.py) (Run coordinator), [`src/rl_gold_trading/data.py`](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/data.py) (Load and split), [`src/rl_gold_trading/metrics.py`](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/metrics.py) (Performance metrics), [`src/rl_gold_trading/vec_env.py`](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/vec_env.py) (Vector environments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market data"]
  node_csv["CSV history"]
  node_hf["Hugging Face dataset"]
  node_data["Load and split<br/>[data.py]"]
  node_features["Market features<br/>[features.py]"]
end

subgraph group_simulation["Trading simulation"]
  node_environment["Trading environment<br/>[envs.py]"]
  node_vecenv["Vector environments<br/>[vec_env.py]"]
end

subgraph group_learning["PPO learning"]
  node_runner["Run coordinator<br/>[run.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_trainer["PPO training<br/>[train.py]"]
  node_ppo["Stable-Baselines3 PPO"]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["Performance metrics<br/>[metrics.py]"]
end

node_user(("User"))
node_entry["CLI entry<br/>[train.py]"]

node_user -->|"starts run"| node_entry
node_entry -->|"dispatches"| node_runner
node_runner -->|"configures"| node_config
node_runner -->|"loads and splits"| node_data
node_data -.->|"reads optionally"| node_csv
node_data -->|"loads fallback"| node_hf
node_runner -->|"computes features"| node_features
node_runner -->|"builds environments"| node_vecenv
node_vecenv -->|"wraps"| node_environment
node_runner -->|"builds and trains"| node_trainer
node_trainer -->|"creates and learns"| node_ppo
node_runner -->|"evaluates splits"| node_metrics
node_metrics -->|"resets and steps"| node_vecenv
node_metrics -->|"predicts actions"| node_ppo

click node_entry "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/train.py"
click node_runner "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/run.py"
click node_config "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/config.py"
click node_data "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/data.py"
click node_features "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/features.py"
click node_environment "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/envs.py"
click node_vecenv "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/vec_env.py"
click node_trainer "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/train.py"
click node_metrics "https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/metrics.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_csv,node_hf,node_data,node_features,node_user toneBlue
class node_environment,node_vecenv toneAmber
class node_runner,node_config,node_trainer,node_ppo toneMint
class node_metrics toneRose
class node_entry toneTeal
```

## Components

### Market data

- **CSV history**
- **Hugging Face dataset**
- [Load and split](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/data.py): `src/rl_gold_trading/data.py`
- [Market features](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/features.py): `src/rl_gold_trading/features.py`

### Trading simulation

- [Trading environment](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/envs.py): `src/rl_gold_trading/envs.py`
- [Vector environments](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/vec_env.py): `src/rl_gold_trading/vec_env.py`

### PPO learning

- [Run coordinator](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/run.py): `src/rl_gold_trading/run.py`
- [Configuration](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/config.py): `src/rl_gold_trading/config.py`
- [PPO training](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/train.py): `src/rl_gold_trading/train.py`
- **Stable-Baselines3 PPO**

### Evaluation

- [Performance metrics](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/src/rl_gold_trading/metrics.py): `src/rl_gold_trading/metrics.py`

### Other components

- **User**
- [CLI entry](https://github.com/jonusnattapong/reinforcement-learning-for-gold-trading/blob/main/train.py): `train.py`

## Connections

- User → CLI entry: starts run (evidence: `README.md`)
- CLI entry → Run coordinator: dispatches (evidence: `train.py`)
- Run coordinator → Configuration: configures (evidence: `src/rl_gold_trading/run.py`)
- Run coordinator → Load and split: loads and splits (evidence: `src/rl_gold_trading/run.py`)
- Load and split → CSV history: reads optionally (evidence: `README.md`)
- Load and split → Hugging Face dataset: loads fallback (evidence: `src/rl_gold_trading/data.py`)
- Run coordinator → Market features: computes features (evidence: `src/rl_gold_trading/run.py`)
- Run coordinator → Vector environments: builds environments (evidence: `src/rl_gold_trading/run.py`)
- Vector environments → Trading environment: wraps (evidence: `src/rl_gold_trading/vec_env.py`)
- Run coordinator → PPO training: builds and trains (evidence: `src/rl_gold_trading/run.py`)
- PPO training → Stable-Baselines3 PPO: creates and learns (evidence: `src/rl_gold_trading/train.py`)
- Run coordinator → Performance metrics: evaluates splits (evidence: `src/rl_gold_trading/run.py`)
- Performance metrics → Vector environments: resets and steps (evidence: `src/rl_gold_trading/metrics.py`)
- Performance metrics → Stable-Baselines3 PPO: predicts actions (evidence: `src/rl_gold_trading/metrics.py`)
