# markdregan/freqai-marcos-lopez-de-prado architecture

> Architecture diagram of the GitHub repository markdregan/freqai-marcos-lopez-de-prado, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/markdregan/freqai-marcos-lopez-de-prado
- Repository: https://github.com/markdregan/freqai-marcos-lopez-de-prado

## Overview

##### Project Type & Purpose
- This is a modular, backend-focused trading engine built on Freqtrade with an ML/“Litmus” extension (FreqAI).
- It provides a CLI and RPC/Web UI for downloading market data, backtesting, hyperparameter optimization, live trading via exchange adapters, and ML‐powered strategies.

##### High-Level Architectural Components
a. Presentation Layer
- CLI (freqtrade/main.py + commands/*)
- RPC/API server (freqtrade/rpc/api_server/*) exposing REST & WebSocket endpoints
- Web UI (embedded static files under rpc/api_server/ui)
- Notification adapters (Telegram, Discord, Webhook)
b. Application/Core Engine
- Core trading loop (freqtrade/worker.py, freqtrade/freqtradebot.py)
- Command dispatch/resolvers (freqtrade/resolvers/*)
- Configuration loader & validator (freqtrade/configuration/*)
- Strategy/plugin manager (freqtrade/strategy/*, plugins/pairlist, plugins/protections)
c. Domain/Business Logic
- Exchange adapters (freqtrade/exchange/*) for live/pre–live REST & WS market data & order execution
- Data handlers & backtesting modules (freqtrade/data/*, freqtrade/optimize/backtesting.py)
- ML components (“Litmus” & FreqAI) for feature engineering, model training, inference (freqtrade/litmus/* + freqtrade/freqai/*)
- Hyperopt engine (freqtrade/optimize/hyperopt*)
d. Infrastructure Layer
- Persistence and state (SQLite/SQLAlchemy models under freqtrade/persistence/*)
- Logging (freqtrade/loggers/*)
- Key-value store & caches (freqtrade/persistence/key_value_store.py, freqtrade/util/periodic_cache.py)
- Docker environment & orchestration (Dockerfile, docker-compose.yml, .devcontainer/*)

##### Interactions & Data-Flow
1. User invokes CLI command → Core Engine
2. Core loads & validates config → Instantiates resolvers → Selects strategy/plugins
3. Core fetches market data via Exchange Adapter → Feeds data to Strategy & Data Handlers
4. Strategy generates signals → Execution via Exchange Adapter
5. Orders, trades, metrics persist to DB / key-value store → Logging subsystem
6. RPC/API server exposes state & metrics → Client UIs (web browser, external scripts)
7. ML workflows (FreqAI/Litmus) integrate in backtesting & live loops for prediction

##### Key Architectural Patterns & Principles
- Plugin/Extension Pattern: strategies, pairlists, protections, resolvers load dynamically
- Layered Separation: Presentation → Application → Domain → Infrastructure
- Dependency Injection via Resolver interfaces
- Modular packaging by feature (commands, exchange, data, optimize, persistence, rpc, strategy)
- Configuration-first approach (JSON/YAML config + env vars)

- Clear component labels matching directory/package names

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI"]:::presentation
        RPC["RPC/API Server"]:::presentation
        WebUI["Web UI"]:::presentation
        Notify["Notification Adapters"]:::presentation
    end

    %% Application/Core Engine Layer
    subgraph "Application/Core Engine"
        Core["Core Engine"]:::core
        Resolvers["Command Dispatch & Resolvers"]:::core
        Config["Configuration Loader & Validator"]:::core
        PluginMgr["Strategy & Plugin Manager"]:::core
    end

    %% Domain/Business Logic Layer
    subgraph "Domain/Business Logic"
        Exchange["Exchange Adapters"]:::domain
        DataHandlers["Data Handlers & Backtesting"]:::domain
        ML["ML Modules (Litmus & FreqAI)"]:::domain
        Hyperopt["Hyperopt Engine"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        Persistence["Persistence & State"]:::infra
        Logging["Logging"]:::infra
        Cache["Key-Value Store & Caches"]:::infra
        Docker["Docker & Orchestration"]:::infra
    end

    %% External Exchanges
    subgraph "External Exchanges"
        Binance["Binance"]:::external
        Kraken["Kraken"]:::external
        Coinbase["Coinbase Pro"]:::external
        OtherExch["..."]:::external
    end

    %% Relationships
    CLI -->|"invoke command"| Core
    RPC -->|"API call"| Core
    Core <-->|"OHLCV request / Order execution"| Exchange
    Core -->|"feed data"| DataHandlers
    Core -->|"invoke ML inference"| ML
    ML -->|"model output"| Core
    Core -->|"persist orders & metrics"| Persistence
    Core -->|"log events"| Logging
    Core -->|"cache reads/writes"| Cache
    Core -->|"send notifications"| Notify
    Core -->|"trigger hyperopt"| Hyperopt
    Docker -->|"hosts"| CLI
    Docker -->|"hosts"| RPC
    Docker -->|"hosts"| Core
    Docker -->|"hosts"| Exchange
    Docker -->|"hosts"| Persistence

    Persistence -->|"SQL/SQLite"| DB[(Database)]:::infra
    Cache -->|"Key-Value Store"| KV[(KV Store)]:::infra

    Exchange --> Binance
    Exchange --> Kraken
    Exchange --> Coinbase
    Exchange --> OtherExch

    %% Click events Presentation Layer
    click CLI "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/main.py"
    click CLI "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/commands/"
    click RPC "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/rpc/api_server/"
    click RPC "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/rpc/rpc.py"
    click WebUI "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/rpc/api_server/ui/"
    click Notify "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/rpc/telegram.py"
    click Notify "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/rpc/discord.py"
    click Notify "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/rpc/webhook.py"

    %% Click events Core
    click Core "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/worker.py"
    click Core "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/freqtradebot.py"
    click Resolvers "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/resolvers/"
    click Config "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/configuration/"
    click PluginMgr "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/strategy/"
    click PluginMgr "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/plugins/pairlist/"
    click PluginMgr "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/plugins/protections/"

    %% Click events Domain
    click Exchange "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/exchange/"
    click DataHandlers "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/data/"
    click DataHandlers "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/optimize/backtesting.py"
    click ML "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/litmus/"
    click ML "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/freqai/"
    click Hyperopt "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/optimize/hyperopt.py"

    %% Click events Infrastructure
    click Persistence "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/persistence/"
    click Logging "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/freqtrade/loggers/"
    click Cache "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/persistence/key_value_store.py"
    click Cache "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/freqtrade/util/periodic_cache.py"
    click Docker "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/Dockerfile"
    click Docker "https://github.com/markdregan/freqai-marcos-lopez-de-prado/blob/litmus-ai/docker-compose.yml"
    click Docker "https://github.com/markdregan/freqai-marcos-lopez-de-prado/tree/litmus-ai/.devcontainer/"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef core fill:#DFFFD0,stroke:#4CAF50,stroke-width:2px
    classDef domain fill:#FFF4D0,stroke:#FF9800,stroke-width:2px
    classDef infra fill:#F0F0F0,stroke:#9E9E9E,stroke-width:2px
    classDef external fill:#FFE0E0,stroke:#E53935,stroke-width:2px,stroke-dasharray: 5 5
```
