# ai4finance-foundation/finrl-meta architecture

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

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

## Overview

##### Project type and purpose
- FinRL-Meta is an open-source framework and benchmarking library for data-driven financial reinforcement learning. It provides a “metaverse” of market environments (stock, crypto, futures, FX, portfolio optimization, execution) and prebuilt pipelines for training, testing, and trading DRL agents.
- Key indicators: three-layer architecture (data, environment, agent), plug-and-play support for multiple DRL libraries (ElegantRL, Stable-Baselines3, RLlib), dozens of demos and benchmarks.

##### File structure
- Top-level directories
- agents/ – wrappers for different DRL libraries
- meta/ – core modules: data processing (meta/data_processors), environment implementations (meta/env_*), configuration
- examples/ – demo notebooks and scripts showing how to run environments and agents
- docker/ – container build & run scripts
- unit_tests/ – data-source validation tests
- main.py, train.py, test.py, trade.py – orchestrators for the training-testing-trading pipeline
- Config and build files
- requirements.txt, setup.py – packaging & dependencies
- .github/workflows – CI for linting and Python tests
- figs/ – reference images for documentation
- Patterns
- Layered architecture: data layer (data fetching & processing), environment layer (gym-style envs), agent layer (algorithmic wrappers)
- Plug-and-play design: agents/<library> imports meta/env_* environments via a unified interface

##### README for additional insights
- Three logical layers:
1) Data layer: raw data ingestion via many APIs → preprocessed OHLCV + features
2) Environment layer: gym environments for different markets/use cases
3) Agent layer: algorithms from multiple DRL frameworks
- Training-Testing-Trading pipeline with strict separation of time windows
- DataOps pipeline: automated end-to-end data processing, sampling, and monitoring

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Sources
    subgraph "External Data Sources" 
        API["APIs: Akshare, Alpaca, Binance, CCXT, YahooFinance, etc"]:::external
    end
    click API "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/data_processors/"

    %% DataOps Pipeline & Data Layer
    API -->|"fetch_data()"| DataOps["DataOps Pipeline\n(meta/data_processor.py)"]:::data
    click DataOps "https://github.com/ai4finance-foundation/finrl-meta/blob/master/meta/data_processor.py"
    DataOps -->|"stores raw & features"| RawData[(Raw & Preprocessed Data)]:::storage

    %% Environment Layer
    subgraph "Environment Layer" 
        StockEnv["Stock Trading Env"]:::env
        CryptoEnv["Crypto Trading Env"]:::env
        FuturesEnv["Futures Trading Env"]:::env
        FXEnv["FX Trading Env"]:::env
        ExecOptimEnv["Execution Optimization Env"]:::env
        PortAllocEnv["Portfolio Allocation Env"]:::env
        PortOptEnv["Portfolio Optimization Env"]:::env
    end
    click StockEnv "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/env_stock_trading/"
    click CryptoEnv "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/env_crypto_trading/"
    click FuturesEnv "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/env_future_trading/"
    click FXEnv "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/env_fx_trading/"
    click ExecOptimEnv "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/env_execution_optimizing/"
    click PortAllocEnv "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/env_portfolio_allocation/"
    click PortOptEnv "https://github.com/ai4finance-foundation/finrl-meta/tree/master/meta/env_portfolio_optimization/"

    RawData -->|"reset()/step()"| StockEnv
    RawData --> CryptoEnv
    RawData --> FuturesEnv
    RawData --> FXEnv
    RawData --> ExecOptimEnv
    RawData --> PortAllocEnv
    RawData --> PortOptEnv

    %% Agent Layer
    subgraph "Agent Layer" 
        ERL["ElegantRL Wrappers"]:::agent
        SB3["Stable-Baselines3 Wrappers"]:::agent
        RLlib["RLlib Wrappers"]:::agent
    end
    click ERL "https://github.com/ai4finance-foundation/finrl-meta/blob/master/agents/elegantrl_models.py"
    click ERL "https://github.com/ai4finance-foundation/finrl-meta/blob/master/agents/elegantrl_models_wt.py"
    click SB3 "https://github.com/ai4finance-foundation/finrl-meta/blob/master/agents/stablebaselines3_models.py"
    click RLlib "https://github.com/ai4finance-foundation/finrl-meta/blob/master/agents/rllib_models.py"

    StockEnv -->|"env API"| ERL
    StockEnv --> SB3
    StockEnv --> RLlib
    CryptoEnv --> ERL
    CryptoEnv --> SB3
    CryptoEnv --> RLlib
    FuturesEnv --> ERL
    FXEnv --> ERL
    ExecOptimEnv --> ERL
    PortAllocEnv --> ERL
    PortOptEnv --> ERL

    %% Orchestration & CLI
    subgraph "Orchestration & CLI" 
        Main["main.py"]:::orchestration
        Train["train.py"]:::orchestration
        Test["test.py"]:::orchestration
        Trade["trade.py"]:::orchestration
    end
    click Main "https://github.com/ai4finance-foundation/finrl-meta/blob/master/main.py"
    click Train "https://github.com/ai4finance-foundation/finrl-meta/blob/master/train.py"
    click Test "https://github.com/ai4finance-foundation/finrl-meta/blob/master/test.py"
    click Trade "https://github.com/ai4finance-foundation/finrl-meta/blob/master/trade.py"

    ERL -->|"train()/test()/trade()"| Train
    SB3 --> Train
    RLlib --> Train
    Train --> Test
    Test --> Trade

    %% Demo & Examples
    subgraph "Demo & Examples" 
        Demos["examples/"]:::examples
    end
    click Demos "https://github.com/ai4finance-foundation/finrl-meta/tree/master/examples/"
    Trade --> Demos

    %% Containerization
    subgraph "Containerization" 
        Dockerfile["Dockerfile"]:::infra
        Build["build_container.sh"]:::infra
        Start["start_notebook.sh"]:::infra
        TestScript["test.sh"]:::infra
    end
    click Dockerfile "https://github.com/ai4finance-foundation/finrl-meta/tree/master/docker/Dockerfile"
    click Build "https://github.com/ai4finance-foundation/finrl-meta/blob/master/docker/bin/build_container.sh"
    click Start "https://github.com/ai4finance-foundation/finrl-meta/blob/master/docker/bin/start_notebook.sh"
    click TestScript "https://github.com/ai4finance-foundation/finrl-meta/blob/master/docker/bin/test.sh"

    %% Container wraps Orchestration
    subgraph "Docker Container" 
        Main
        Train
        Test
        Trade
    end

    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef data fill:#bbf,stroke:#333,stroke-width:1px
    classDef storage fill:#ccf,stroke:#333,stroke-width:1px
    classDef env fill:#bfb,stroke:#333,stroke-width:1px
    classDef agent fill:#fb7,stroke:#333,stroke-width:1px
    classDef orchestration fill:#ccc,stroke:#333,stroke-width:1px
    classDef examples fill:#ffb,stroke:#333,stroke-width:1px
    classDef infra fill:#ffa,stroke:#333,stroke-width:1px
```
