# saamy4r/freqtrade_reply architecture

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

- Interactive diagram: https://gitdiagram.com/saamy4r/freqtrade_reply
- Repository: https://github.com/saamy4r/freqtrade_reply

## Overview

Freqtrade Replay is a command-line harness that runs the real Freqtrade bot over historical local candle data. The workflow parses replay options, validates or downloads missing data, then advances virtual time while a replay exchange serves historical candles and simulated fills; results are persisted for FreqUI and analysis, with an optional HTML report. The runner and exchange excerpts support the principal runtime links; README statements cover documented output compatibility and automatic downloads.

Main entry points: [`runner.py`](https://github.com/saamy4r/freqtrade_reply/blob/main/runner.py) (Replay runner), [`exchange.py`](https://github.com/saamy4r/freqtrade_reply/blob/main/exchange.py) (Replay exchange), [`data_store.py`](https://github.com/saamy4r/freqtrade_reply/blob/main/data_store.py) (Candle data store), [`cli.py`](https://github.com/saamy4r/freqtrade_reply/blob/main/cli.py) (Replay CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Replay entry"]
  node_cli["Replay CLI<br/>[cli.py]"]
  node_runner["Replay runner<br/>[runner.py]"]
end

subgraph group_simulation["Replay simulation"]
  node_exchange["Replay exchange<br/>[exchange.py]"]
  node_clock["Virtual clock<br/>[clock.py]"]
  node_bot["Freqtrade bot"]
end

subgraph group_data["Historical data"]
  node_download["Freqtrade downloader"]
  node_feather[("Feather data")]
  node_store["Candle data store<br/>[data_store.py]"]
end

subgraph group_results["Results"]
  node_sqlite[("Replay SQLite DB")]
  node_summary["Run summary<br/>[runner.py]"]
  node_report["HTML report<br/>[runner.py]"]
end

node_user(("Operator"))

node_user -->|"runs with options"| node_cli
node_cli -->|"starts replay"| node_runner
node_runner -->|"loads and validates"| node_store
node_runner -->|"downloads missing data"| node_download
node_feather -.->|"provides candles"| node_store
node_runner -->|"starts and advances"| node_clock
node_runner -->|"installs replay exchange"| node_exchange
node_exchange -->|"reads candle data"| node_store
node_exchange -->|"reads replay time"| node_clock
node_runner -->|"drives processing"| node_bot
node_bot -.->|"requests market data and fills"| node_exchange
node_bot -.->|"persists trades"| node_sqlite
node_runner -->|"prints statistics"| node_summary
node_runner -->|"writes optional report"| node_report

click node_cli "https://github.com/saamy4r/freqtrade_reply/blob/main/cli.py"
click node_runner "https://github.com/saamy4r/freqtrade_reply/blob/main/runner.py"
click node_store "https://github.com/saamy4r/freqtrade_reply/blob/main/data_store.py"
click node_exchange "https://github.com/saamy4r/freqtrade_reply/blob/main/exchange.py"
click node_clock "https://github.com/saamy4r/freqtrade_reply/blob/main/clock.py"
click node_summary "https://github.com/saamy4r/freqtrade_reply/blob/main/runner.py"
click node_report "https://github.com/saamy4r/freqtrade_reply/blob/main/runner.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_runner toneBlue
class node_exchange,node_clock,node_bot toneAmber
class node_download,node_feather,node_store toneMint
class node_sqlite,node_summary,node_report toneRose
class node_user toneIndigo
```

## Components

### Replay entry

- [Replay CLI](https://github.com/saamy4r/freqtrade_reply/blob/main/cli.py): `cli.py`
- [Replay runner](https://github.com/saamy4r/freqtrade_reply/blob/main/runner.py): `runner.py`

### Replay simulation

- [Replay exchange](https://github.com/saamy4r/freqtrade_reply/blob/main/exchange.py): `exchange.py`
- [Virtual clock](https://github.com/saamy4r/freqtrade_reply/blob/main/clock.py): `clock.py`
- **Freqtrade bot**

### Historical data

- **Freqtrade downloader**
- **Feather data**
- [Candle data store](https://github.com/saamy4r/freqtrade_reply/blob/main/data_store.py): `data_store.py`

### Results

- **Replay SQLite DB**
- [Run summary](https://github.com/saamy4r/freqtrade_reply/blob/main/runner.py): `runner.py`
- [HTML report](https://github.com/saamy4r/freqtrade_reply/blob/main/runner.py): `runner.py`

### Other components

- **Operator**

## Connections

- Operator → Replay CLI: runs with options (evidence: `cli.py`)
- Replay CLI → Replay runner: starts replay (evidence: `cli.py`)
- Replay runner → Candle data store: loads and validates (evidence: `runner.py`)
- Replay runner → Freqtrade downloader: downloads missing data (evidence: `runner.py`)
- Feather data → Candle data store: provides candles
- Replay runner → Virtual clock: starts and advances (evidence: `runner.py`)
- Replay runner → Replay exchange: installs replay exchange (evidence: `runner.py`)
- Replay exchange → Candle data store: reads candle data (evidence: `exchange.py`)
- Replay exchange → Virtual clock: reads replay time (evidence: `exchange.py`)
- Replay runner → Freqtrade bot: drives processing (evidence: `runner.py`)
- Freqtrade bot → Replay exchange: requests market data and fills
- Freqtrade bot → Replay SQLite DB: persists trades (evidence: `README.md`)
- Replay runner → Run summary: prints statistics (evidence: `runner.py`)
- Replay runner → HTML report: writes optional report (evidence: `runner.py`)
