# ai4finance-foundation/finrl-trading architecture

> Architecture diagram of the GitHub repository ai4finance-foundation/finrl-trading, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai4finance-foundation/finrl-trading
- Repository: https://github.com/ai4finance-foundation/finrl-trading

## Overview

##### Project Type and Purpose
- This is a modular data‐driven trading pipeline (not a web app). It ingests market+fundamental data, preprocesses/feature‐engineers it, then runs two “decision” engines – a Supervised Learning (SL) stock‐selection engine and a Deep Reinforcement Learning (DRL) portfolio‐allocation engine – followed by backtesting and (optionally) live paper‐trading deployment.

##### File Structure Analysis
Top-level:
- .devcontainer/ – Docker‐based dev environment
- README.md – high‐level project overview and phases
- requirements.txt – Python dependencies
- china_stock_market_run.py – deployment script for China markets
- fundamental_run_model.py, fundamental_portfolio_drl.py, ml_model.py, rl_model.py – core modules
- fundamental_*.ipynb, stock_selection.ipynb, backtesting notebooks – research & prototyping
- data_processor/ – data‐ingestion & feature‐engineering notebooks, CSV, outputs
- old_repo_ensemble_strategy/ – packaged DRL ensemble strategy code, configs, raw/trained data

##### Readme Insights
- Phases I–III map directly to modular components:
Phase I: Data ingestion + feature engineering
Phase IIa: SL‐based stock selection + backtesting
Phase IIb: DRL ensemble portfolio allocation + backtesting
Phase III: Deployment to online trading (e.g., Alpaca or Chinese broker API)

##### Main System Components
A. External Data Providers
- Market Data APIs or CSV dumps (Yahoo Finance, AlphaVantage, local CSV)
- Fundamental Data (S&P 500 constituents, financial ratios)
B. Data Processor Module (data_processor/)
- Notebooks & scripts: Step1_get_sp500_ticker, Step2_preprocess_fundamental_data
- Outputs: final_ratios.csv, sector*.xlsx
C. Stock Selection Engine (Supervised Learning)
- ml_model.py / stock_selection.ipynb
- Classic algorithms: LSTM, RF, SVM, Linear/Lasso/Ridge
- fundamental_run_model.py, fundamental_portfolio.ipynb
D. Portfolio Allocation Engine (Deep RL)
- old_repo_ensemble_strategy/ package + rl_model.py / fundamental_portfolio_drl.py
- Algorithms: PPO, DDPG, A2C, SAC, TD3
- backtesting.ipynb, run_DRL.py, trained_models/
E. Backtesting & Evaluation
- fundamental_back_testing.ipynb, old_repo_ensemble_strategy/backtesting.ipynb
- Metrics calculation (returns, Sharpe, drawdown)
F. Deployment Module
- china_stock_market_run.py (China markets)
- (Optional) Alpaca paper trading notebook/script

##### Relationships & Data Flow
- Data Providers → Data Processor → “Processed Data”
- Processed Data → SL Engine → Selected Stock List
- Selected Stock List + Processed Data → DRL Engine → Position Signals
- Signals → Backtesting Module → Performance Reports
- (Optional) Position Signals → Deployment Module → Live/Paper Trading API

##### Architectural Patterns & Principles
- Pipeline Architecture: clearly‐defined stages (staging, modeling, evaluation, deployment)
- Modular design: each engine in its own directory or script for separation of concerns
- Config‐driven: old_repo_ensemble_strategy/config/config.py for hyperparameters
- Reusability: data_processor outputs feed both SL and DRL

##### Technologies & Frameworks
- Python, Jupyter Notebooks
- Pandas, NumPy for data processing
- Scikit‐Learn for SL algorithms
- FinRL / Stable Baselines for DRL algorithms
- Docker (.devcontainer) for consistent environment
- Alpaca (or alternative broker API) for deployment

- Clear labels (e.g., “SL Stock Selector”)
- Versioned config file indicator (config.py)
- Docker/devcontainer boundary to show environment encapsulation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Dev Environment
    subgraph "Development Environment"
        DC[".devcontainer"]:::dev
    end

    %% External Data Providers
    subgraph "External Data Providers"
        SPCSV["S&P 500 Historical Components & Changes (08-12-2022).csv"]:::dataIO
        TICKERS["sp500_tickers.txt"]:::dataIO
        ETF["ETF_SPY_2009_2020.csv"]:::dataIO
        DJI["^DJI.csv"]:::dataIO
        TURB["dow30_turbulence_index.csv"]:::dataIO
        DOW30["dow_30_2009_2020.csv"]:::dataIO
    end

    %% Data Processor Module
    subgraph "Data Processor Module" 
        DP["data_processor"]:::dataIO
        STEP1["Step1_get_sp500_ticker.ipynb"]:::dataIO
        STEP2["Step2_preprocess_fundmental_data.ipynb"]:::dataIO
        OUTPUTS["Processed Data Outputs"]:::dataIO
        CSV["final_ratios.csv"]:::datastore
        SECTORS["sector10.xlsx … sector60.xlsx"]:::datastore
    end

    %% SL Engine
    subgraph "Stock Selection Engine (SL)" 
        ML["ml_model.py"]:::sl
        RUNFUND["fundamental_run_model.py"]:::sl
        NB1["stock_selection.ipynb"]:::sl
        NB2["fundamental_portfolio.ipynb"]:::sl
    end

    %% DRL Engine
    subgraph "Portfolio Allocation Engine (DRL)" 
        OLD["old_repo_ensemble_strategy"]:::drl
        RL["rl_model.py"]:::drl
        DRLRUN["fundamental_portfolio_drl.py"]:::drl
        RUNDRL["run_DRL.py"]:::drl
        CFG["config.py"]:::drl
        MODELS["models.py"]:::drl
        PREPROC["preprocessors.py"]:::drl
    end

    %% Backtesting & Evaluation
    subgraph "Backtesting & Evaluation"
        FB["fundamental_back_testing.ipynb"]:::eval
        OB["backtesting.ipynb"]:::eval
    end

    %% Deployment Module
    subgraph "Deployment Module"
        CHINA["china_stock_market_run.py"]:::deploy
    end

    %% Data Flow
    SPCSV -->|ingest| STEP1
    TICKERS -->|ingest| STEP1
    ETF -->|ingest| OLD
    DJI -->|ingest| OLD
    TURB -->|ingest| OLD
    DOW30 -->|ingest| OLD

    STEP1 --> STEP2
    STEP2 -->|generates| CSV
    STEP2 -->|generates| SECTORS
    CSV --> OUTPUTS
    SECTORS --> OUTPUTS

    OUTPUTS --> ML
    OUTPUTS --> RUNFUND
    ML -->|"selected stocks"| NB1
    RUNFUND --> NB2

    OUTPUTS --> RL
    NB1 --> DRLRUN
    DRLRUN --> OLD
    OLD --> PREPROC
    PREPROC --> MODELS
    MODELS -->|"position signals"| RUNDRL

    RUNDRL --> FB
    RUNDRL --> OB
    RUNDRL --> CHINA

    %% Click Events
    click SPCSV "https://github.com/ai4finance-foundation/finrl-trading/blob/master/data_processor/S&P 500 Historical Components & Changes(08-12-2022).csv"
    click TICKERS "https://github.com/ai4finance-foundation/finrl-trading/blob/master/data_processor/sp500_tickers.txt"
    click ETF "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/data/ETF_SPY_2009_2020.csv"
    click DJI "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/data/^DJI.csv"
    click TURB "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/data/dow30_turbulence_index.csv"
    click DOW30 "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/data/dow_30_2009_2020.csv"
    click DP "https://github.com/ai4finance-foundation/finrl-trading/tree/master/data_processor/"
    click STEP1 "https://github.com/ai4finance-foundation/finrl-trading/blob/master/data_processor/Step1_get_sp500_ticker.ipynb"
    click STEP2 "https://github.com/ai4finance-foundation/finrl-trading/blob/master/data_processor/Step2_preprocess_fundmental_data.ipynb"
    click CSV "https://github.com/ai4finance-foundation/finrl-trading/blob/master/data_processor/outputs/final_ratios.csv"
    click SECTORS "https://github.com/ai4finance-foundation/finrl-trading/blob/master/data_processor/outputs/sector10.xlsx"
    click ML "https://github.com/ai4finance-foundation/finrl-trading/blob/master/ml_model.py"
    click RUNFUND "https://github.com/ai4finance-foundation/finrl-trading/blob/master/fundamental_run_model.py"
    click NB1 "https://github.com/ai4finance-foundation/finrl-trading/blob/master/stock_selection.ipynb"
    click NB2 "https://github.com/ai4finance-foundation/finrl-trading/blob/master/fundamental_portfolio.ipynb"
    click RL "https://github.com/ai4finance-foundation/finrl-trading/blob/master/rl_model.py"
    click DRLRUN "https://github.com/ai4finance-foundation/finrl-trading/blob/master/fundamental_portfolio_drl.py"
    click OLD "https://github.com/ai4finance-foundation/finrl-trading/tree/master/old_repo_ensemble_strategy/"
    click RUNDRL "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/run_DRL.py"
    click CFG "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/config/config.py"
    click MODELS "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/model/models.py"
    click PREPROC "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/preprocessing/preprocessors.py"
    click FB "https://github.com/ai4finance-foundation/finrl-trading/blob/master/fundamental_back_testing.ipynb"
    click OB "https://github.com/ai4finance-foundation/finrl-trading/blob/master/old_repo_ensemble_strategy/backtesting.ipynb"
    click CHINA "https://github.com/ai4finance-foundation/finrl-trading/blob/master/china_stock_market_run.py"
    click DC "https://github.com/ai4finance-foundation/finrl-trading/tree/master/.devcontainer/Dockerfile"
    click DC "https://github.com/ai4finance-foundation/finrl-trading/blob/master/.devcontainer/devcontainer.json"

    %% Styles
    classDef dataIO fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef datastore fill:#FFFFFF,stroke:#0366D6,stroke-dasharray: 5 5,color:#0366D6;
    classDef sl fill:#DFF5D0,stroke:#228B22,color:#228B22;
    classDef drl fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00;
    classDef eval fill:#F0E5FF,stroke:#800080,color:#800080;
    classDef deploy fill:#F5D0FF,stroke:#800080,color:#800080;
    classDef dev fill:#EEEEEE,stroke:#888888,color:#555555;
```
