# vigentocommerce/freqtrade architecture

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

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

## Overview

##### Main Components
- Bot Engine/Command Line Interface (CLI): The central module starting out from freqtrade/__main__.py and the commands in freqtrade/commands that handle user input.
- Configuration & Persistence: The configuration modules under freqtrade/configuration load settings and manage validations, while persistence is achieved using SQLite and the modules in freqtrade/persistence.
- Exchange Integration: Modules in freqtrade/exchange (and tests under tests/exchange) encapsulate integration with Binance, Kraken, OKX, etc. They include helper utilities and exchange-specific scripts.
- Data Management & Backtesting: Components in freqtrade/data and freqtrade/optimize (with history handlers and converters) handle historical data download, backtesting, and backtesting analysis.
- Strategy & Signal Processing: Under freqtrade/strategy and related templates, this component encapsulates trading strategies, including the execution logic and analysis.
- FreqAI / Machine Learning Module: The freqtrade/freqai directory contains reinforcement learning environments, prediction models, base models, and tensorboard support—all related to machine learning-based strategy optimization.
- RPC / Web UI / Telegram Integration: The rpc module (in freqtrade/rpc) covers the API server, web server, websocket endpoints, and integrations for external control via Telegram.
- Logging & Monitoring: Modules located in freqtrade/loggers and user_data logs (as well as tests) show where logging is configured and how it feeds into UI or CLI outputs.
- Docker & Deployment: Dockerfiles, docker-compose files, and the devcontainer configuration indicate containerization components for deployment and development.

##### Relationships & Interactions
- The CLI and commands module acts as the entry point that parses user requests (e.g., trade, backtesting, hyperopt) and delegates tasks to the core engine.
- The configuration system feeds dynamic settings and environment variables across the various modules (exchange, strategy, persistence).
- The exchange integration layer communicates with external crypto exchanges. This component interacts with modules for handling API requests/responses and error handling.
- The engine’s trading logic (strategy execution) consumes live or historical market data (provided by the data management/backtesting modules) to decide on orders. This flow is bolstered by the signal processing components.
- The machine learning (FreqAI) module processes the market data and signals to fine-tune strategy parameters; it interacts with data preparation, reinforcement learning components, and logging (for monitoring performance via Tensorboard).
- RPC components wrap around functionalities (accessed via web UI/Telegram) that expose trading commands, real-time status updates, and administrative actions.
- Logging and persistence ensure data is captured (into SQLite or files) and also help with error diagnosis.

##### Architectural Patterns & Technologies
- Modular design: The project is divided into many cohesive modules (commands, configuration, exchange, strategy, etc.), reflecting separation of concerns.
- Plugin architecture: The pairlist and protection managers show how algorithms for trade filtering and risk management are kept hence extensible.
- Client/server communication: RPC (with asynchronous web server) and Telegram integration are used for remote control.
- Containerization: Usage of Dockerfiles and docker-compose for environment consistency.
- Testing Driven: Comprehensive tests indicate adherence to unit/integration testing best practices.
- Machine Learning integration: FreqAI uses reinforcement learning environments and prediction models to adapt the trading logic.

##### Instructing the Principal Software Engineer
- User input modules and the command processing engine.
- The trading engine and both live market data (via exchange integration) and historical data (backtesting modules).
- The ML modules (FreqAI) with data ingestion pipelines and strategy optimization workflows.
- Core engine internals (e.g., business logic, trading decisions)
- External interactions (exchanges, Telegram, web API)
- Support systems (logging, persistence, configuration)
- Finally, ensure that deployment elements such as Docker configuration and CI/CD pipelines (from the .github/workflows folder) are also represented, even if at a high level, to give a complete picture of how the system is built and deployed.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI_CLI["CLI Entry Point"]:::ui
        UI_RPC["RPC / Web UI / Telegram Integration"]:::ui
    end

    %% Application Layer
    subgraph "Application Layer"
        TRADING["Trading Engine"]:::app
        APP_CFG["Configuration & Persistence"]:::app
        EXCH["Exchange Integration"]:::app
        STRAT["Strategy & Signal Processing"]:::app
    end

    %% Data & Machine Learning Layer
    subgraph "Data & Machine Learning Layer"
        DATA["Data Management & Backtesting"]:::data
        FREQAI["FreqAI / Machine Learning"]:::data
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        INF_LOG["Logging & Monitoring"]:::infra
        INF_DEP["Docker & Deployment"]:::infra
    end

    %% Connections between layers
    UI_CLI -->|"sendsCommand"| TRADING
    UI_RPC -->|"sendsCommand"| TRADING

    TRADING -->|"loadsConfig"| APP_CFG
    TRADING -->|"executesOrder"| EXCH
    TRADING -->|"appliesStrategy"| STRAT
    TRADING -->|"fetchesData"| DATA

    DATA -->|"providesData"| FREQAI
    FREQAI -->|"optimizes"| STRAT

    TRADING -->|"logsTo"| INF_LOG
    APP_CFG -->|"logsTo"| INF_LOG
    STRAT -->|"logsTo"| INF_LOG

    INF_DEP -.->|"deployment"| TRADING

    %% Click Events
    click UI_CLI "https://github.com/vigentocommerce/freqtrade/blob/develop/freqtrade/__main__.py"
    click UI_CLI "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/commands"

    click APP_CFG "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/configuration"
    click APP_CFG "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/persistence"

    click EXCH "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/exchange"

    click DATA "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/data"
    click DATA "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/optimize"

    click STRAT "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/strategy"
    click STRAT "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/templates"

    click FREQAI "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/freqai"

    click UI_RPC "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/rpc"

    click INF_LOG "https://github.com/vigentocommerce/freqtrade/tree/develop/freqtrade/loggers"
    click INF_LOG "https://github.com/vigentocommerce/freqtrade/tree/develop/user_data/logs"

    click INF_DEP "https://github.com/vigentocommerce/freqtrade/tree/develop/Dockerfile"
    click INF_DEP "https://github.com/vigentocommerce/freqtrade/blob/develop/docker-compose.yml"
    click INF_DEP "https://github.com/vigentocommerce/freqtrade/tree/develop/docker"
    click INF_DEP "https://github.com/vigentocommerce/freqtrade/blob/develop/.devcontainer"

    %% Styles
    classDef ui fill:#f9c,stroke:#000,stroke-width:2px;
    classDef app fill:#ccf,stroke:#000,stroke-width:2px;
    classDef data fill:#cfc,stroke:#000,stroke-width:2px;
    classDef infra fill:#ffc,stroke:#000,stroke-width:2px;
```
