# ai-yang/alphapilot architecture

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

- Interactive diagram: https://gitdiagram.com/ai-yang/alphapilot
- Repository: https://github.com/ai-yang/alphapilot

## Overview

AlphaPilot is a stock-quant research and trading platform. A typical workflow prepares market data, mines and evaluates factors, saves promising strategies, then produces daily signals or deploys them through a controlled live runtime. The Web portal and research API expose shared jobs and results; backtesting, visualization, notifications, and formula-based miners are additional capabilities. The README documents the major product stages and runtime links; source excerpts confirm selected engine, data, mining, and durable-task responsibilities. Other subsystem links are documented rather than inferred from unsampled implementation.

Main entry points: [`alphapilot/research/tasks.py`](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/research/tasks.py) (Durable Tasks), [`alphapilot/app/cli.py`](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/app/cli.py) (Command Line), [`alphapilot/systems/factor/database.py`](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/factor/database.py) (Factor Library), [`alphapilot/modules/alpha_mining`](https://github.com/ai-yang/alphapilot/tree/main/alphapilot/modules/alpha_mining) (Factor Mining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User Access"]
  node_portal["Web Portal<br/>[module.py]"]
  node_research_api["Research API<br/>[api.py]"]
  node_cli["Command Line<br/>[cli.py]"]
  node_tasks["Durable Tasks<br/>[tasks.py]"]
  node_task_store[("Task Store<br/>[store.py]")]
end

subgraph group_research["Research Workflow"]
  node_engine["Kernel Engine<br/>[engine.py]"]
  node_miners["Factor Mining"]
  node_formula_miners["Formula Miners"]
  node_factor_store[("Factor Library<br/>[database.py]")]
  node_backtest["Backtest Evaluation<br/>[service.py]"]
  node_strategy["Strategy Assets<br/>[service.py]"]
  node_daily_signals["Daily Signals<br/>[module.py]"]
end

subgraph group_market["Market Systems"]
  node_data["Data Preparation<br/>[prepare_cn.py]"]
  node_data_sources["Data Adapters"]
end

subgraph group_trading["Trading Runtime"]
  node_live_runtime["Live Runtime<br/>[runtime.py]"]
  node_risk_oms["Risk and OMS"]
  node_broker_gateway["Broker Gateway<br/>[gateway.py]"]
end

subgraph group_operations["Operations"]
  node_backtest_viz["Backtest Views"]
  node_notifications["Notifications<br/>[service.py]"]
end

node_user(("Researcher"))
node_mcp(("MCP Client"))
node_llm(("LLM Provider"))
node_market_provider(("Market Data Provider"))
node_broker(("Broker Service"))
node_notify_channels(("Telegram, Feishu, Email"))

node_user -->|"uses"| node_portal
node_user -->|"runs commands"| node_cli
node_mcp -->|"connects"| node_research_api
node_portal -->|"shares jobs"| node_tasks
node_research_api -->|"submits jobs"| node_tasks
node_tasks -->|"persists jobs"| node_task_store
node_tasks -->|"builds engine"| node_engine
node_cli -->|"prepares data"| node_data
node_data -->|"downloads from"| node_data_sources
node_market_provider -->|"provides prices"| node_data_sources
node_cli -->|"starts mining"| node_miners
node_cli -->|"starts mining"| node_formula_miners
node_miners -.->|"requests generation"| node_llm
node_formula_miners -->|"emits factors"| node_factor_store
node_miners -.->|"adds candidates"| node_factor_store
node_factor_store -->|"evaluates factors"| node_backtest
node_backtest -->|"visualizes results"| node_backtest_viz
node_factor_store -->|"selects factors"| node_strategy
node_strategy -->|"delegates training"| node_backtest
node_strategy -->|"generates signals"| node_daily_signals
node_daily_signals -->|"supplies targets"| node_live_runtime
node_live_runtime -->|"routes through"| node_risk_oms
node_risk_oms -->|"dispatches orders"| node_broker_gateway
node_broker_gateway -->|"sends orders"| node_broker
node_tasks -.->|"reports completion"| node_notifications
node_notifications -->|"delivers alerts"| node_notify_channels

click node_portal "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/modules/portal/module.py"
click node_research_api "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/research/api.py"
click node_cli "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/app/cli.py"
click node_tasks "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/research/tasks.py"
click node_task_store "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/research/store.py"
click node_engine "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/kernel/engine.py"
click node_data "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/data/prepare_cn.py"
click node_data_sources "https://github.com/ai-yang/alphapilot/tree/main/alphapilot/adapters/builtin/data_source"
click node_miners "https://github.com/ai-yang/alphapilot/tree/main/alphapilot/modules/alpha_mining"
click node_formula_miners "https://github.com/ai-yang/alphapilot/tree/main/alphapilot/modules/alphaforge"
click node_factor_store "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/factor/database.py"
click node_backtest "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/backtest/service.py"
click node_strategy "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/strategy/service.py"
click node_daily_signals "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/modules/daily_trade/module.py"
click node_live_runtime "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/live/runtime.py"
click node_risk_oms "https://github.com/ai-yang/alphapilot/tree/main/alphapilot/systems/live"
click node_broker_gateway "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/live/gateway.py"
click node_backtest_viz "https://github.com/ai-yang/alphapilot/tree/main/alphapilot/modules/backtest_viz"
click node_notifications "https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/notify/service.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_portal,node_research_api,node_cli,node_tasks,node_task_store,node_mcp toneBlue
class node_engine,node_miners,node_formula_miners,node_factor_store,node_backtest,node_strategy,node_daily_signals toneAmber
class node_data,node_data_sources toneMint
class node_live_runtime,node_risk_oms,node_broker_gateway toneRose
class node_backtest_viz,node_notifications,node_user,node_llm,node_market_provider,node_broker,node_notify_channels toneIndigo
```

## Components

### User Access

- [Web Portal](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/modules/portal/module.py): `alphapilot/modules/portal/module.py`
- [Research API](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/research/api.py): `alphapilot/research/api.py`
- [Command Line](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/app/cli.py): `alphapilot/app/cli.py`
- [Durable Tasks](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/research/tasks.py): `alphapilot/research/tasks.py`
- [Task Store](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/research/store.py): `alphapilot/research/store.py`

### Research Workflow

- [Kernel Engine](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/kernel/engine.py): `alphapilot/kernel/engine.py`
- [Factor Mining](https://github.com/ai-yang/alphapilot/tree/main/alphapilot/modules/alpha_mining): `alphapilot/modules/alpha_mining`
- [Formula Miners](https://github.com/ai-yang/alphapilot/tree/main/alphapilot/modules/alphaforge): `alphapilot/modules/alphaforge`
- [Factor Library](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/factor/database.py): `alphapilot/systems/factor/database.py`
- [Backtest Evaluation](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/backtest/service.py): `alphapilot/systems/backtest/service.py`
- [Strategy Assets](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/strategy/service.py): `alphapilot/systems/strategy/service.py`
- [Daily Signals](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/modules/daily_trade/module.py): `alphapilot/modules/daily_trade/module.py`

### Market Systems

- [Data Preparation](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/data/prepare_cn.py): `alphapilot/systems/data/prepare_cn.py`
- [Data Adapters](https://github.com/ai-yang/alphapilot/tree/main/alphapilot/adapters/builtin/data_source): `alphapilot/adapters/builtin/data_source`

### Trading Runtime

- [Live Runtime](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/live/runtime.py): `alphapilot/systems/live/runtime.py`
- [Risk and OMS](https://github.com/ai-yang/alphapilot/tree/main/alphapilot/systems/live): `alphapilot/systems/live`
- [Broker Gateway](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/live/gateway.py): `alphapilot/systems/live/gateway.py`

### Operations

- [Backtest Views](https://github.com/ai-yang/alphapilot/tree/main/alphapilot/modules/backtest_viz): `alphapilot/modules/backtest_viz`
- [Notifications](https://github.com/ai-yang/alphapilot/blob/main/alphapilot/systems/notify/service.py): `alphapilot/systems/notify/service.py`

### Other components

- **Researcher**
- **MCP Client**
- **LLM Provider**
- **Market Data Provider**
- **Broker Service**
- **Telegram, Feishu, Email**

## Connections

- Researcher → Web Portal: uses (evidence: `README.md`)
- Researcher → Command Line: runs commands (evidence: `README.md`)
- MCP Client → Research API: connects (evidence: `README.md`)
- Web Portal → Durable Tasks: shares jobs (evidence: `README.md`)
- Research API → Durable Tasks: submits jobs (evidence: `README.md`)
- Durable Tasks → Task Store: persists jobs (evidence: `alphapilot/research/tasks.py`)
- Durable Tasks → Kernel Engine: builds engine (evidence: `alphapilot/research/tasks.py`)
- Command Line → Data Preparation: prepares data (evidence: `README.md`)
- Data Preparation → Data Adapters: downloads from (evidence: `README.md`)
- Market Data Provider → Data Adapters: provides prices (evidence: `README.md`)
- Command Line → Factor Mining: starts mining (evidence: `README.md`)
- Command Line → Formula Miners: starts mining (evidence: `README.md`)
- Factor Mining → LLM Provider: requests generation
- Formula Miners → Factor Library: emits factors (evidence: `alphapilot/modules/alphaforge/pipeline.py`)
- Factor Mining → Factor Library: adds candidates
- Factor Library → Backtest Evaluation: evaluates factors (evidence: `README.md`)
- Backtest Evaluation → Backtest Views: visualizes results (evidence: `README.md`)
- Factor Library → Strategy Assets: selects factors (evidence: `alphapilot/systems/strategy/service.py`)
- Strategy Assets → Backtest Evaluation: delegates training (evidence: `alphapilot/systems/strategy/service.py`)
- Strategy Assets → Daily Signals: generates signals (evidence: `README.md`)
- Daily Signals → Live Runtime: supplies targets (evidence: `README.md`)
- Live Runtime → Risk and OMS: routes through (evidence: `README.md`)
- Risk and OMS → Broker Gateway: dispatches orders (evidence: `README.md`)
- Broker Gateway → Broker Service: sends orders (evidence: `README.md`)
- Durable Tasks → Notifications: reports completion
- Notifications → Telegram, Feishu, Email: delivers alerts (evidence: `README.md`)