# phongquach239/freqtrade architecture

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

- Interactive diagram: https://gitdiagram.com/phongquach239/freqtrade
- Repository: https://github.com/phongquach239/freqtrade

## Overview

##### Project Type and Purpose
- This is a full-stack, Python-based crypto-trading bot (Freqtrade) that provides:
- A CLI tool (“freqtrade” command)
- A built-in web UI / REST & WebSocket API server
- Telegram/Discord RPC integration
- Backtesting, hyperparameter optimization (Hyperopt), edge-sizing, plotting, and FreqAI (ML) modules
- Live trading via multiple exchange adapters (REST & WS) with persistence (SQLite)

##### Top-Level Architecture Components
a. User Interfaces
- CLI
- Web UI (served by FastAPI/Uvicorn in freqtrade/rpc/api_server)
- Telegram/Discord bots (freqtrade/rpc/telegram.py, discord.py)
b. Core Engine
- Command dispatcher & CLI options (freqtrade/commands)
- Configuration loader & validator (freqtrade/configuration)
- Strategy executor & wrapper (freqtrade/strategy)
- Data provider & history manager (freqtrade/data)
- Backtesting & analysis (freqtrade/optimize, freqtrade/data/btanalysis)
- Hyperopt subsystem (freqtrade/optimize/hyperopt)
- Edge-position sizing (freqtrade/edge)
- Plotting & reporting (freqtrade/plot)
- FreqAI ML models & RL environments (freqtrade/freqai)
c. Adapters & Infrastructure
- Exchange adapters (REST + WS) for Binance, Kraken, etc. (freqtrade/exchange)
- Persistence layer with SQLite / SQLAlchemy (freqtrade/persistence)
- Plugin loaders (pairlist, protections) (freqtrade/plugins)
- RPC manager & message routing (freqtrade/rpc/rpc_manager.py)
d. External Services
- Exchanges (via CCXT underneath exchange modules)
- Telegram API
- Discord API
- (Optional) other webhook endpoints

##### Relationships & Data Flows
- User → CLI/Web UI/Telegram → RPC Manager → Core Engine
- Core Engine queries config subsystem, then:
- For live trading: Data Provider pulls live market data from Exchange WS/REST → Strategy module generates signals → Exchange adapter executes orders → Persistence records trades
- For backtesting: Data Provider retrieves historical data (feather/parquet/json) → Backtest engine simulates strategy → Reporting & Plotting
- For hyperopt: Hyperopt engine generates parameter sets → Backtest engine → Hyperopt loss evaluator → Result stored in user_data/hyperopts
- For FreqAI: Data Kitchen prepares features → ML model trains/predicts → Strategy uses predictions
- Persistence is a common sink for configs, live trades, backtest results, logs

##### Architectural Patterns & Principles
- Hexagonal (Ports & Adapters): Core engine is isolated from exchanges, UIs, persistence via well-defined interfaces and resolvers (freqtrade/resolvers)
- Plugin architecture: Pairlist and protection filters loaded dynamically via plugin managers
- Single responsibility: Separate modules for commands, data handling, strategy logic, execution, ML, optimization
- Asynchronous I/O: Web server and exchange WS clients leverage asyncio (freqtrade/system/asyncio_config)
- Config-driven: The entire setup is driven by a unified JSON config schema (freqtrade/config_schema)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        style UI fill:#d0e7ff,stroke:#333,stroke-width:1px
        CLI["CLI Tool"]:::ui
        WebUI["Web UI (FastAPI/Uvicorn)"]:::ui
        TelegramBot["Telegram Bot"]:::ui
        DiscordBot["Discord Bot"]:::ui
    end

    %% API / RPC
    RPCManager["RPC Manager & Message Routing"]:::core

    %% Core Engine
    subgraph "Core Engine"
        style CORE fill:#d0ffd6,stroke:#333,stroke-width:1px
        CommandDispatcher["Command Dispatcher"]:::core
        ConfigLoader["Configuration Loader & Validator"]:::core
        DataProvider["Data Provider & History Manager"]:::core
        StrategyExecutor["Strategy Executor"]:::core
        EdgeSizing["Edge-Position Sizing"]:::core
        Backtester["Backtesting & Analysis"]:::core
        Hyperopt["Hyperopt Subsystem"]:::core
        FreqAI["FreqAI (ML)"]:::core
        PlotReporting["Plotting & Reporting"]:::core
    end

    %% Adapters & External
    subgraph "Adapters & External Services"
        style ADAPTER fill:#ffe6b3,stroke:#333,stroke-width:1px
        ExchangeAdapters["Exchange Adapters (REST & WS)"]:::adapter
        PluginLoaders["Plugin Loaders"]:::adapter
        SQLiteDB[(SQLite DB)]:::persistence
        TelegramAPI["Telegram API"]:::external
        DiscordAPI["Discord API"]:::external
        ExternalExchanges["External Exchanges (CCXT)"]:::external
    end

    %% Connections
    CLI -->|uses| RPCManager
    WebUI -->|API calls| RPCManager
    TelegramBot -->|RPC commands| RPCManager
    DiscordBot -->|RPC commands| RPCManager

    RPCManager -->|dispatches| CommandDispatcher
    CommandDispatcher -->|loads| ConfigLoader
    ConfigLoader -->|provides config| DataProvider
    DataProvider -->|feeds| StrategyExecutor
    DataProvider -->|provides history| Backtester
    StrategyExecutor -->|signals| ExchangeAdapters
    StrategyExecutor -->|saves trades| SQLiteDB
    ExchangeAdapters -->|REST/WS| ExternalExchanges
    Backtester -->|simulates| SQLiteDB
    Hyperopt -->|optimizes| Backtester
    FreqAI -->|features| StrategyExecutor
    PlotReporting -->|reads| SQLiteDB
    PlotReporting -->|outputs| WebUI
    PlotReporting -->|outputs| CLI

    %% UI to Reporting
    CLI -->|reports| PlotReporting
    WebUI -->|visualizes| PlotReporting

    %% Plugins
    PluginLoaders -->|loads| CommandDispatcher
    PluginLoaders -->|loads| StrategyExecutor

    %% Persistence
    SQLiteDB ---|stores| ConfigLoader

    %% Click Events
    click CLI "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/__main__.py"
    click CommandDispatcher "https://github.com/phongquach239/freqtrade/tree/develop/freqtrade/commands/"
    click WebUI "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/rpc/api_server/webserver.py"
    click TelegramBot "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/rpc/telegram.py"
    click DiscordBot "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/rpc/discord.py"
    click RPCManager "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/rpc/rpc_manager.py"
    click ConfigLoader "https://github.com/phongquach239/freqtrade/tree/develop/freqtrade/configuration/"
    click DataProvider "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/data/dataprovider.py"
    click StrategyExecutor "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/strategy/strategy_wrapper.py"
    click EdgeSizing "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/edge/edge_positioning.py"
    click Backtester "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/optimize/backtesting.py"
    click Hyperopt "https://github.com/phongquach239/freqtrade/tree/develop/freqtrade/optimize/hyperopt/"
    click FreqAI "https://github.com/phongquach239/freqtrade/tree/develop/freqtrade/freqai/"
    click PlotReporting "https://github.com/phongquach239/freqtrade/blob/develop/freqtrade/plot/plotting.py"
    click ExchangeAdapters "https://github.com/phongquach239/freqtrade/tree/develop/freqtrade/exchange/"
    click PluginLoaders "https://github.com/phongquach239/freqtrade/tree/develop/freqtrade/plugins/"
    click SQLiteDB "https://github.com/phongquach239/freqtrade/tree/develop/freqtrade/persistence/"

    %% Styles
    classDef ui fill:#d0e7ff,stroke:#333,stroke-width:1px
    classDef core fill:#d0ffd6,stroke:#333,stroke-width:1px
    classDef adapter fill:#ffe6b3,stroke:#333,stroke-width:1px
    classDef persistence fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
```
