# ziadfrancis/reinforcement_trading_part_2 architecture

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

- Interactive diagram: https://gitdiagram.com/ziadfrancis/reinforcement_trading_part_2
- Repository: https://github.com/ziadfrancis/reinforcement_trading_part_2

## Overview

1. This is a file-based research pipeline for XAUUSD minute data, not an online service. The core flow is: raw MT4/MT5 CSV → validated time-aligned bars → causal features → trading environment / baselines → walk-forward evaluation → saved artifacts and charts.

2. `config.py` is the central boundary for experiment setup. It controls the source dataset, timezones, resampling/decision timeframe, split strategy, walk-forward fold counts, PPO settings, and the default paths used by the rest of the pipeline.

3. `data_loader.py` owns the ingestion layer. It parses broker-style CSVs, handles EET/EEST time normalization, shifts M1 candle timestamps to candle-close semantics, validates continuity/shape, and prepares data for resampling into higher decision bars while retaining M1 for intrabar execution simulation.

4. `features.py` is the feature-engineering subsystem. It builds the causal, mostly stationary observation matrix used by both baselines and RL, with ATR/price-normalized distances, ratios, session flags, and candle-shape features. The README indicates the final observation set is 25 features, with some highly collinear candidates intentionally removed.

5. `env_bracket.py` defines the main simulation boundary: a Gymnasium-compatible bracket-trading environment. It simulates entry/exit logic with direction, stop-loss, and take-profit buckets; uses M1 data to resolve intrabar TP/SL hits; assumes SL-first when both are touched in the same candle; and uses fixed-fractional risk sizing with reward normalized by risk rather than raw PnL.

6. `baselines.py` provides non-RL reference policies, likely including random and rule-based trend-following/EMA-ATR strategies. These are used to sanity-check the pipeline and compare RL performance against simple deterministic or stochastic behaviors.

7. `train_ppo.py` is the RL training subsystem. It trains PPO over the bracket-action environment with a `MultiDiscrete([direction, SL bucket, TP/R bucket])` action space. The README makes clear there are two validation modes: a sliding walk-forward mode that repeatedly retrains and tests on successive out-of-sample windows, and a block walk-forward mode that seals a final holdout and rolls train/validation folds over the rest.

8. `run_pipeline.py` is the main pre-test orchestration entry point. It performs the temporal train/validation/test split, runs the non-RL pipeline end to end, and writes validation-only outputs so the test split stays sealed.

9. `final_holdout_eval.py` is the explicit one-time release gate for the test set. It is the architecture’s “single reveal” boundary: after model selection is frozen, this script evaluates on the sealed holdout and produces the final report.

10. `evaluate.py` and `model_artifacts.py` are the reporting and persistence layer. `evaluate.py` computes trade-level and equity-level metrics such as drawdown and summary statistics, while `model_artifacts.py` likely standardizes how trained models, fold outputs, and CSV reports are stored.

11. `visualize.py` and the notebooks are the analysis layer. They generate charts for candles, indicators, volatility, sessions, feature correlations, trades, equity curves, and drawdowns, while the notebooks provide exploratory comparison across consistency checks, ensembles, and test/fold analyses.

12. `leakage_checks.py` and `training_diagnostics.py` enforce the research boundary against lookahead bias and overfitting. The repo emphasizes future-append stability checks, sealed test splits by default, and fold-level diagnostics so that validation behavior is measured before any final holdout exposure.

13. Overall, the architecture is organized around strict temporal boundaries: raw market history is transformed into causal features, the environment simulates execution with pessimistic intrabar assumptions, and evaluation is done through walk-forward or sealed-holdout protocols. That makes the repo suitable for a diagram with clear layers for ingestion, feature generation, simulation, training, evaluation, and artifact/report output.

Main entry points: [`evaluate.py`](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/evaluate.py) (Evaluate), [`config.py`](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/config.py) (Config), [`features.py`](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/features.py) (Features), [`train_ppo.py`](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/train_ppo.py) (Train PPO)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup"]
  node_config_py["Config<br/>[config.py]"]
end

subgraph group_ingestion["Ingestion"]
  node_data_loader_py["Data Loader<br/>csv ingest<br/>[data_loader.py]"]
  node_features_py["Features<br/>[features.py]"]
end

subgraph group_simulation["Simulation"]
  node_env_bracket_py["Bracket Env<br/>gymnasium env<br/>[env_bracket.py]"]
  node_baselines_py["Baselines<br/>reference policies<br/>[baselines.py]"]
end

subgraph group_training["Training"]
  node_train_ppo_py["Train PPO<br/>rl training<br/>[train_ppo.py]"]
  node_run_pipeline_py["Run Pipeline<br/>pipeline orchestrator<br/>[run_pipeline.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_final_holdout_eval_py["Holdout Eval<br/>sealed test gate"]
  node_evaluate_py["Evaluate<br/>metrics<br/>[evaluate.py]"]
  node_model_artifacts_py["Artifacts<br/>persistence<br/>[model_artifacts.py]"]
end

subgraph group_quality["Quality"]
  node_leakage_checks_py["Leak Checks<br/>bias checks<br/>[leakage_checks.py]"]
  node_training_diagnostics_py["Diagnostics<br/>training checks"]
end

subgraph group_analysis["Analysis"]
  node_visualize_py["Visualize<br/>plots<br/>[visualize.py]"]
  node_view_results_py["Results View<br/>report viewer<br/>[view_results.py]"]
  node_notebooks_set["Notebooks<br/>exploratory analysis"]
end

node_config_py -->|"dataset/timebase"| node_data_loader_py
node_config_py -->|"feature setup"| node_features_py
node_config_py -->|"risk/env params"| node_env_bracket_py
node_config_py -->|"ppo params"| node_train_ppo_py
node_config_py -->|"split policy"| node_run_pipeline_py
node_data_loader_py -->|"bars in"| node_features_py
node_data_loader_py -->|"m1 feed"| node_env_bracket_py
node_features_py -->|"observations"| node_env_bracket_py
node_features_py -->|"inputs"| node_baselines_py
node_env_bracket_py -->|"rl loop"| node_train_ppo_py
node_baselines_py -->|"benchmarks"| node_evaluate_py
node_train_ppo_py -->|"test runs"| node_evaluate_py
node_run_pipeline_py -->|"non-rl run"| node_baselines_py
node_run_pipeline_py -->|"validation metrics"| node_evaluate_py
node_evaluate_py -->|"reports"| node_model_artifacts_py
node_train_ppo_py -->|"checkpoints"| node_model_artifacts_py
node_final_holdout_eval_py -->|"holdout scoring"| node_evaluate_py
node_final_holdout_eval_py -->|"final outputs"| node_model_artifacts_py
node_evaluate_py -->|"metrics plots"| node_visualize_py
node_model_artifacts_py -->|"saved outputs"| node_view_results_py
node_model_artifacts_py -->|"analysis data"| node_notebooks_set
node_leakage_checks_py -.->|"split sanity"| node_data_loader_py
node_leakage_checks_py -.->|"causality"| node_features_py
node_training_diagnostics_py -.->|"fit signals"| node_train_ppo_py
node_training_diagnostics_py -.->|"fold review"| node_evaluate_py
node_visualize_py -.->|"shared analysis"| node_notebooks_set

click node_config_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/config.py"
click node_data_loader_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/data_loader.py"
click node_features_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/features.py"
click node_env_bracket_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/env_bracket.py"
click node_baselines_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/baselines.py"
click node_train_ppo_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/train_ppo.py"
click node_run_pipeline_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/run_pipeline.py"
click node_final_holdout_eval_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/final_holdout_eval.py"
click node_evaluate_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/evaluate.py"
click node_model_artifacts_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/model_artifacts.py"
click node_visualize_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/visualize.py"
click node_view_results_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/view_results.py"
click node_leakage_checks_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/leakage_checks.py"
click node_training_diagnostics_py "https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/training_diagnostics.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_config_py,node_visualize_py,node_view_results_py,node_notebooks_set toneBlue
class node_data_loader_py,node_features_py toneAmber
class node_env_bracket_py,node_baselines_py toneMint
class node_train_ppo_py,node_run_pipeline_py toneRose
class node_final_holdout_eval_py,node_evaluate_py,node_model_artifacts_py toneIndigo
class node_leakage_checks_py,node_training_diagnostics_py toneTeal
```

## Components

### Setup

Central experiment configuration and defaults.

- [Config](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/config.py): experiment config · Defines dataset, time handling, splits, walk-forward settings, and default paths. · `config.py`

### Ingestion

Raw CSV parsing, temporal normalization, and feature construction.

- [Data Loader](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/data_loader.py): csv ingest · Parses broker CSVs, normalizes timestamps, validates continuity, and prepares M1/bars. · `data_loader.py`
- [Features](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/features.py): causal features · Builds stationary observation features for baselines and RL. · `features.py`

### Simulation

Trading environment and baseline policies.

- [Bracket Env](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/env_bracket.py): gymnasium env · Simulates bracket trading with intrabar TP/SL resolution and risk-normalized rewards. · `env_bracket.py`
- [Baselines](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/baselines.py): reference policies · Non-RL benchmark strategies for sanity checks and comparison. · `baselines.py`

### Training

PPO training and orchestration.

- [Train PPO](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/train_ppo.py): rl training · Trains PPO on the bracket environment with discrete direction and risk buckets. · `train_ppo.py`
- [Run Pipeline](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/run_pipeline.py): pipeline orchestrator · Runs the pre-test workflow, including split setup and validation-only execution. · `run_pipeline.py`

### Evaluation

Walk-forward testing, holdout scoring, and persisted outputs.

- [Holdout Eval](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/final_holdout_eval.py): sealed test gate · Performs the one-time final evaluation on the sealed holdout set. · `final_holdout_eval.py`
- [Evaluate](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/evaluate.py): metrics · Computes trade-level and equity-level performance statistics. · `evaluate.py`
- [Artifacts](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/model_artifacts.py): persistence · Standardizes saved models, fold outputs, and CSV reports. · `model_artifacts.py`

### Quality

Leakage prevention and diagnostics.

- [Leak Checks](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/leakage_checks.py): bias checks · Detects lookahead and future-append leakage across temporal splits. · `leakage_checks.py`
- [Diagnostics](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/training_diagnostics.py): training checks · Tracks fold-level behavior and overfitting signals during training. · `training_diagnostics.py`

### Analysis

Charts, result inspection, and notebook exploration.

- [Visualize](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/visualize.py): plots · Generates charts for candles, indicators, equity, drawdowns, and trade outcomes. · `visualize.py`
- [Results View](https://github.com/ziadfrancis/reinforcement_trading_part_2/blob/main/view_results.py): report viewer · Inspects stored experiment outputs and summaries. · `view_results.py`
- **Notebooks**: exploratory analysis · Interactive analyses for consistency checks, ensemble comparison, and fold/test review.

## Connections

- Config → Data Loader: dataset/timebase · Provides source, timezone, and resampling settings.
- Config → Features: feature setup · Controls observation construction and experiment defaults.
- Config → Bracket Env: risk/env params · Sets trading and decision-timeframe assumptions.
- Config → Train PPO: ppo params · Defines training hyperparameters and fold strategy.
- Config → Run Pipeline: split policy · Drives train/validation/test orchestration.
- Data Loader → Features: bars in · Feeds validated and time-aligned market data into feature generation.
- Data Loader → Bracket Env: m1 feed · Supplies minute data for intrabar TP/SL execution simulation.
- Features → Bracket Env: observations · Provides the causal state used by the agent and baselines.
- Features → Baselines: inputs · Supplies indicators and state variables for rule-based policies.
- Bracket Env → Train PPO: rl loop · Defines the action/reward interaction for PPO.
- Baselines → Evaluate: benchmarks · Produces reference trade streams for comparison.
- Train PPO → Evaluate: test runs · Sends trained policies into evaluation.
- Run Pipeline → Baselines: non-rl run · Executes baseline pipeline end to end.
- Run Pipeline → Evaluate: validation metrics · Computes validation-only performance summaries.
- Evaluate → Artifacts: reports · Persists metrics and fold outputs.
- Train PPO → Artifacts: checkpoints · Stores learned policies and training artifacts.
- Holdout Eval → Evaluate: holdout scoring · Runs final metrics on the sealed test set.
- Holdout Eval → Artifacts: final outputs · Writes the final frozen reports and artifacts.
- Evaluate → Visualize: metrics plots · Feeds equity and trade statistics into charts.
- Artifacts → Results View: saved outputs · Provides stored runs for inspection.
- Artifacts → Notebooks: analysis data · Supports exploratory comparison and post-run analysis.
- Leak Checks → Data Loader: split sanity · Checks temporal integrity around ingestion and alignment.
- Leak Checks → Features: causality · Verifies features do not leak future information.
- Diagnostics → Train PPO: fit signals · Monitors training stability and overfitting.
- Diagnostics → Evaluate: fold review · Summarizes validation behavior across walk-forward folds.
- Visualize → Notebooks: shared analysis · Charts complement notebook-based exploration.