# lifanc/quant-flow-docs architecture

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

- Interactive diagram: https://gitdiagram.com/lifanc/quant-flow-docs
- Repository: https://github.com/lifanc/quant-flow-docs

## Overview

Quant Flow is a command-line stock screener and historical backtester. Its main workflow loads symbols and prices, normalizes data, derives moving-average signals, simulates account trades and a buy-and-hold benchmark, then exports metrics, charts, and replay inputs. Screening and historical-run comparison are separate user-facing capabilities. The README documents the current account model; unsampled modules are represented only where the source index or README supports their role, so some internal links are omitted.

Main entry points: [`src/quant_flow/main.py`](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/main.py) (Run coordinator), [`src/quant_flow/screening.py`](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/screening.py) (Symbol screening), [`src/quant_flow/backtest/execution.py`](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/backtest/execution.py) (Target execution), [`src/quant_flow/backtest/account_simulator.py`](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/backtest/account_simulator.py) (Account backtest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command workflow"]
  node_cli["CLI arguments<br/>[cli.py]"]
  node_runner["Run coordinator<br/>[main.py]"]
end

subgraph group_data["Market data"]
  node_symbols["Watchlist loader<br/>[symbols.py]"]
  node_yahoo["Yahoo prices<br/>[yahoo_finance.py]"]
  node_csvprices["CSV price loader<br/>[csv_provider.py]"]
  node_normalize["Price normalizer<br/>[normalizer.py]"]
  node_csvformat["CSV format<br/>[csv_format.py]"]
end

subgraph group_research["Screening and strategy"]
  node_screen["Symbol screening<br/>[screening.py]"]
  node_ma["Moving averages<br/>[moving_average.py]"]
  node_signal["Trade events<br/>[signal.py]"]
end

subgraph group_simulation["Account simulation"]
  node_account["Account backtest"]
  node_execution["Target execution<br/>[execution.py]"]
  node_order["Order model<br/>[order.py]"]
  node_fill["Fill model<br/>[fill.py]"]
  node_portfolio["Cash and holdings<br/>[portfolio.py]"]
  node_position["Position model<br/>[position.py]"]
end

subgraph group_results["Analysis and reports"]
  node_metrics["Performance metrics<br/>[metrics.py]"]
  node_exporter["Report exporter<br/>[exporter.py]"]
  node_charts["Equity charts<br/>[charts.py]"]
  node_guide["Report guide<br/>[guide.py]"]
  node_comparison["Run comparison<br/>[comparison.py]"]
end

node_user(("Investor"))

node_user -->|"sets options"| node_cli
node_cli -->|"starts run"| node_runner
node_runner -->|"parses options"| node_cli
node_runner -->|"loads symbols"| node_symbols
node_runner -->|"dispatches screening"| node_screen
node_screen -->|"downloads prices"| node_yahoo
node_screen -->|"applies rule"| node_ma
node_screen -->|"loads watchlist"| node_symbols
node_screen -->|"writes results"| node_csvformat
node_runner -->|"downloads prices"| node_yahoo
node_runner -->|"loads saved prices"| node_csvprices
node_csvprices -->|"reads CSV"| node_csvformat
node_runner -->|"normalizes prices"| node_normalize
node_runner -->|"calculates signals"| node_ma
node_runner -->|"generates events"| node_signal
node_runner -->|"runs strategy and benchmark"| node_account
node_account -->|"validates data"| node_normalize
node_account -->|"executes targets"| node_execution
node_execution -->|"creates orders"| node_order
node_execution -->|"creates fills"| node_fill
node_execution -->|"updates account"| node_portfolio
node_portfolio -->|"applies fills"| node_position
node_position -->|"applies fill"| node_fill
node_runner -->|"calculates performance"| node_metrics
node_runner -->|"exports reports"| node_exporter
node_runner -->|"saves chart"| node_charts
node_runner -->|"writes guide"| node_guide
node_user -->|"compares runs"| node_comparison
node_symbols -->|"uses headers"| node_csvformat

click node_cli "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/cli.py"
click node_runner "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/main.py"
click node_symbols "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/symbols.py"
click node_yahoo "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/providers/yahoo_finance.py"
click node_csvprices "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/providers/csv_provider.py"
click node_normalize "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/normalizer.py"
click node_csvformat "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/csv_format.py"
click node_screen "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/screening.py"
click node_ma "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/strategy/moving_average.py"
click node_signal "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/signals/signal.py"
click node_account "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/backtest/account_simulator.py"
click node_execution "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/backtest/execution.py"
click node_order "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/orders/order.py"
click node_fill "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/fills/fill.py"
click node_portfolio "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/portfolio/portfolio.py"
click node_position "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/positions/position.py"
click node_metrics "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/performance/metrics.py"
click node_exporter "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/exporter.py"
click node_charts "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/charts.py"
click node_guide "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/guide.py"
click node_comparison "https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/comparison.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_symbols,node_yahoo,node_csvprices,node_normalize,node_csvformat toneAmber
class node_screen,node_ma,node_signal toneMint
class node_account,node_execution,node_order,node_fill,node_portfolio,node_position toneRose
class node_metrics,node_exporter,node_charts,node_guide,node_comparison,node_user toneIndigo
```

## Components

### Command workflow

- [CLI arguments](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/cli.py): `src/quant_flow/cli.py`
- [Run coordinator](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/main.py): `src/quant_flow/main.py`

### Market data

- [Watchlist loader](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/symbols.py): `src/quant_flow/data/symbols.py`
- [Yahoo prices](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/providers/yahoo_finance.py): `src/quant_flow/data/providers/yahoo_finance.py`
- [CSV price loader](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/providers/csv_provider.py): `src/quant_flow/data/providers/csv_provider.py`
- [Price normalizer](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/normalizer.py): `src/quant_flow/data/normalizer.py`
- [CSV format](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/data/csv_format.py): `src/quant_flow/data/csv_format.py`

### Screening and strategy

- [Symbol screening](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/screening.py): `src/quant_flow/screening.py`
- [Moving averages](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/strategy/moving_average.py): `src/quant_flow/strategy/moving_average.py`
- [Trade events](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/signals/signal.py): `src/quant_flow/signals/signal.py`

### Account simulation

- [Account backtest](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/backtest/account_simulator.py): `src/quant_flow/backtest/account_simulator.py`
- [Target execution](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/backtest/execution.py): `src/quant_flow/backtest/execution.py`
- [Order model](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/orders/order.py): `src/quant_flow/orders/order.py`
- [Fill model](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/fills/fill.py): `src/quant_flow/fills/fill.py`
- [Cash and holdings](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/portfolio/portfolio.py): `src/quant_flow/portfolio/portfolio.py`
- [Position model](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/positions/position.py): `src/quant_flow/positions/position.py`

### Analysis and reports

- [Performance metrics](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/performance/metrics.py): `src/quant_flow/performance/metrics.py`
- [Report exporter](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/exporter.py): `src/quant_flow/reporting/exporter.py`
- [Equity charts](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/charts.py): `src/quant_flow/reporting/charts.py`
- [Report guide](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/guide.py): `src/quant_flow/reporting/guide.py`
- [Run comparison](https://github.com/lifanc/quant-flow-docs/blob/master/src/quant_flow/reporting/comparison.py): `src/quant_flow/reporting/comparison.py`

### Other components

- **Investor**

## Connections

- Investor → CLI arguments: sets options (evidence: `README.md`)
- CLI arguments → Run coordinator: starts run (evidence: `README.md`)
- Run coordinator → CLI arguments: parses options (evidence: `src/quant_flow/main.py`)
- Run coordinator → Watchlist loader: loads symbols (evidence: `src/quant_flow/main.py`)
- Run coordinator → Symbol screening: dispatches screening (evidence: `src/quant_flow/main.py`)
- Symbol screening → Yahoo prices: downloads prices (evidence: `src/quant_flow/screening.py`)
- Symbol screening → Moving averages: applies rule (evidence: `src/quant_flow/screening.py`)
- Symbol screening → Watchlist loader: loads watchlist (evidence: `src/quant_flow/screening.py`)
- Symbol screening → CSV format: writes results (evidence: `src/quant_flow/screening.py`)
- Run coordinator → Yahoo prices: downloads prices (evidence: `src/quant_flow/main.py`)
- Run coordinator → CSV price loader: loads saved prices (evidence: `src/quant_flow/main.py`)
- CSV price loader → CSV format: reads CSV (evidence: `src/quant_flow/data/providers/csv_provider.py`)
- Run coordinator → Price normalizer: normalizes prices (evidence: `src/quant_flow/main.py`)
- Run coordinator → Moving averages: calculates signals (evidence: `src/quant_flow/main.py`)
- Run coordinator → Trade events: generates events (evidence: `src/quant_flow/main.py`)
- Run coordinator → Account backtest: runs strategy and benchmark (evidence: `src/quant_flow/main.py`)
- Account backtest → Price normalizer: validates data (evidence: `src/quant_flow/backtest/account_simulator.py`)
- Account backtest → Target execution: executes targets (evidence: `src/quant_flow/backtest/account_simulator.py`)
- Target execution → Order model: creates orders (evidence: `src/quant_flow/backtest/execution.py`)
- Target execution → Fill model: creates fills (evidence: `src/quant_flow/backtest/execution.py`)
- Target execution → Cash and holdings: updates account (evidence: `src/quant_flow/backtest/execution.py`)
- Cash and holdings → Position model: applies fills (evidence: `src/quant_flow/portfolio/portfolio.py`)
- Position model → Fill model: applies fill (evidence: `src/quant_flow/positions/position.py`)
- Run coordinator → Performance metrics: calculates performance (evidence: `src/quant_flow/main.py`)
- Run coordinator → Report exporter: exports reports (evidence: `src/quant_flow/main.py`)
- Run coordinator → Equity charts: saves chart (evidence: `src/quant_flow/main.py`)
- Run coordinator → Report guide: writes guide (evidence: `src/quant_flow/main.py`)
- Investor → Run comparison: compares runs (evidence: `README.md`)
- Watchlist loader → CSV format: uses headers (evidence: `src/quant_flow/data/symbols.py`)
