# blave-tw/blave-agent architecture

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

- Interactive diagram: https://gitdiagram.com/blave-tw/blave-agent
- Repository: https://github.com/blave-tw/blave-agent

## Overview

Blave Agent is an agentic quant workspace: users describe an idea, an AI agent creates strategy code, and the workspace supports research, evaluation, and deterministic live execution. The map follows that path from desktop interaction through backtesting and validation to portfolio management and venue orders, with cloud messaging/reporting as a separate access branch. README claims establish several subsystem capabilities; sampled source is partial, so uncertain internal wiring is omitted.

Main entry points: [`lib/runner.py`](https://github.com/blave-tw/blave-agent/blob/main/lib/runner.py) (Backtest Runner), [`lib/execute.py`](https://github.com/blave-tw/blave-agent/blob/main/lib/execute.py) (Order Execution), [`runtime`](https://github.com/blave-tw/blave-agent/tree/main/runtime) (Web / Telegram), [`runtime/agent_turn.py`](https://github.com/blave-tw/blave-agent/blob/main/runtime/agent_turn.py) (Agent Turn)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Workspace"]
  node_desktop_ui["Desktop UI<br/>[app.js]"]
  node_desktop_main["Desktop Main<br/>[main.js]"]
  node_agent_turn["Agent Turn<br/>[agent_turn.py]"]
  node_session_store[("Session Store<br/>[session_store.py]")]
end

subgraph group_research["Strategy Research"]
  node_strategies["Strategy Code"]
  node_market_data["Market Data<br/>[data.py]"]
  node_backtest_runner["Backtest Runner<br/>[runner.py]"]
  node_validation["Backtest Validation<br/>[validation.py]"]
  node_param_scan["Parameter Scan<br/>[param_scan.py]"]
  node_walk_forward["Walk Forward<br/>[walk_forward.py]"]
  node_quality["Quality Checks<br/>[quality_check.py]"]
  node_reports["Reports<br/>[report.py]"]
end

subgraph group_trading["Portfolio Trading"]
  node_manager["Portfolio Manager<br/>[manager.py]"]
  node_allocator["Allocation Methods<br/>[allocator.py]"]
  node_scheduler["Strategy Scheduler<br/>[runner.py]"]
  node_reconciler["Position Reconciler<br/>[reconciler.py]"]
  node_execution["Order Execution<br/>[execute.py]"]
  node_venue["Venue Adapters<br/>[venue_wiring.py]"]
  node_kill_switch["Exposure Guard<br/>[guard.py]"]
  node_paper_orders["Paper Trading<br/>[order_paper.py]"]
end

subgraph group_cloud["Cloud Access"]
  node_cloud_bridges["Web / Telegram"]
  node_cloud_agent["Cloud Agent Runtime<br/>[local_daemon.py]"]
end

node_user(("User"))
node_ai_cli{{"Claude / Codex"}}
node_exchange{{"Exchanges / Brokers"}}
node_blave_service{{"Blave Services"}}
node_telegram{{"Telegram"}}

node_user -->|"describes idea"| node_desktop_ui
node_desktop_ui -->|"sends commands"| node_desktop_main
node_desktop_main -->|"starts turn"| node_agent_turn
node_agent_turn -->|"invokes"| node_ai_cli
node_agent_turn -->|"persists turns"| node_session_store
node_ai_cli -->|"writes strategy"| node_strategies
node_strategies -->|"runs strategy"| node_backtest_runner
node_backtest_runner -->|"fetches prices"| node_market_data
node_backtest_runner -->|"validates results"| node_validation
node_backtest_runner -.->|"scans parameters"| node_param_scan
node_backtest_runner -.->|"tests out-of-sample"| node_walk_forward
node_backtest_runner -->|"checks results"| node_quality
node_backtest_runner -->|"produces report"| node_reports
node_manager -->|"computes weights"| node_allocator
node_manager -->|"updates targets"| node_reconciler
node_strategies -->|"scheduled code"| node_scheduler
node_scheduler -->|"provides targets"| node_reconciler
node_reconciler -->|"requests orders"| node_execution
node_execution -->|"checks exposure"| node_kill_switch
node_execution -->|"dispatches orders"| node_venue
node_venue -->|"places orders"| node_exchange
node_execution -.->|"paper fills"| node_paper_orders
node_user -->|"sends messages"| node_cloud_bridges
node_cloud_bridges -->|"forwards messages"| node_cloud_agent
node_cloud_agent -->|"invokes"| node_ai_cli
node_cloud_agent -->|"requests data"| node_blave_service
node_cloud_bridges -->|"bridges chat"| node_telegram
node_cloud_bridges -->|"shows reports"| node_reports

click node_desktop_ui "https://github.com/blave-tw/blave-agent/blob/main/shell/renderer/app.js"
click node_desktop_main "https://github.com/blave-tw/blave-agent/blob/main/shell/main.js"
click node_agent_turn "https://github.com/blave-tw/blave-agent/blob/main/runtime/agent_turn.py"
click node_session_store "https://github.com/blave-tw/blave-agent/blob/main/runtime/session_store.py"
click node_strategies "https://github.com/blave-tw/blave-agent/tree/main/strategies"
click node_market_data "https://github.com/blave-tw/blave-agent/blob/main/lib/data.py"
click node_backtest_runner "https://github.com/blave-tw/blave-agent/blob/main/lib/runner.py"
click node_validation "https://github.com/blave-tw/blave-agent/blob/main/lib/validation.py"
click node_param_scan "https://github.com/blave-tw/blave-agent/blob/main/lib/param_scan.py"
click node_walk_forward "https://github.com/blave-tw/blave-agent/blob/main/lib/walk_forward.py"
click node_quality "https://github.com/blave-tw/blave-agent/blob/main/lib/quality_check.py"
click node_reports "https://github.com/blave-tw/blave-agent/blob/main/lib/report.py"
click node_manager "https://github.com/blave-tw/blave-agent/blob/main/manager/manager.py"
click node_allocator "https://github.com/blave-tw/blave-agent/blob/main/lib/allocator.py"
click node_scheduler "https://github.com/blave-tw/blave-agent/blob/main/lib/runner.py"
click node_reconciler "https://github.com/blave-tw/blave-agent/blob/main/manager/reconciler.py"
click node_execution "https://github.com/blave-tw/blave-agent/blob/main/lib/execute.py"
click node_venue "https://github.com/blave-tw/blave-agent/blob/main/lib/venue_wiring.py"
click node_kill_switch "https://github.com/blave-tw/blave-agent/blob/main/lib/guard.py"
click node_cloud_bridges "https://github.com/blave-tw/blave-agent/tree/main/runtime"
click node_cloud_agent "https://github.com/blave-tw/blave-agent/blob/main/runtime/local_daemon.py"
click node_paper_orders "https://github.com/blave-tw/blave-agent/blob/main/lib/order_paper.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_desktop_ui,node_desktop_main,node_agent_turn,node_session_store,node_user toneBlue
class node_strategies,node_market_data,node_backtest_runner,node_validation,node_param_scan,node_walk_forward,node_quality,node_reports toneAmber
class node_manager,node_allocator,node_scheduler,node_reconciler,node_execution,node_venue,node_kill_switch,node_paper_orders toneMint
class node_cloud_bridges,node_cloud_agent toneRose
class node_ai_cli,node_exchange,node_blave_service,node_telegram toneIndigo
```

## Components

### Desktop Workspace

- [Desktop UI](https://github.com/blave-tw/blave-agent/blob/main/shell/renderer/app.js): `shell/renderer/app.js`
- [Desktop Main](https://github.com/blave-tw/blave-agent/blob/main/shell/main.js): `shell/main.js`
- [Agent Turn](https://github.com/blave-tw/blave-agent/blob/main/runtime/agent_turn.py): `runtime/agent_turn.py`
- [Session Store](https://github.com/blave-tw/blave-agent/blob/main/runtime/session_store.py): `runtime/session_store.py`

### Strategy Research

- [Strategy Code](https://github.com/blave-tw/blave-agent/tree/main/strategies): `strategies`
- [Market Data](https://github.com/blave-tw/blave-agent/blob/main/lib/data.py): `lib/data.py`
- [Backtest Runner](https://github.com/blave-tw/blave-agent/blob/main/lib/runner.py): `lib/runner.py`
- [Backtest Validation](https://github.com/blave-tw/blave-agent/blob/main/lib/validation.py): `lib/validation.py`
- [Parameter Scan](https://github.com/blave-tw/blave-agent/blob/main/lib/param_scan.py): `lib/param_scan.py`
- [Walk Forward](https://github.com/blave-tw/blave-agent/blob/main/lib/walk_forward.py): `lib/walk_forward.py`
- [Quality Checks](https://github.com/blave-tw/blave-agent/blob/main/lib/quality_check.py): `lib/quality_check.py`
- [Reports](https://github.com/blave-tw/blave-agent/blob/main/lib/report.py): `lib/report.py`

### Portfolio Trading

- [Portfolio Manager](https://github.com/blave-tw/blave-agent/blob/main/manager/manager.py): `manager/manager.py`
- [Allocation Methods](https://github.com/blave-tw/blave-agent/blob/main/lib/allocator.py): `lib/allocator.py`
- [Strategy Scheduler](https://github.com/blave-tw/blave-agent/blob/main/lib/runner.py): `lib/runner.py`
- [Position Reconciler](https://github.com/blave-tw/blave-agent/blob/main/manager/reconciler.py): `manager/reconciler.py`
- [Order Execution](https://github.com/blave-tw/blave-agent/blob/main/lib/execute.py): `lib/execute.py`
- [Venue Adapters](https://github.com/blave-tw/blave-agent/blob/main/lib/venue_wiring.py): `lib/venue_wiring.py`
- [Exposure Guard](https://github.com/blave-tw/blave-agent/blob/main/lib/guard.py): `lib/guard.py`
- [Paper Trading](https://github.com/blave-tw/blave-agent/blob/main/lib/order_paper.py): `lib/order_paper.py`

### Cloud Access

- [Web / Telegram](https://github.com/blave-tw/blave-agent/tree/main/runtime): `runtime`
- [Cloud Agent Runtime](https://github.com/blave-tw/blave-agent/blob/main/runtime/local_daemon.py): `runtime/local_daemon.py`

### Other components

- **User**
- **Claude / Codex**
- **Exchanges / Brokers**
- **Blave Services**
- **Telegram**

## Connections

- User → Desktop UI: describes idea
- Desktop UI → Desktop Main: sends commands
- Desktop Main → Agent Turn: starts turn
- Agent Turn → Claude / Codex: invokes
- Agent Turn → Session Store: persists turns
- Claude / Codex → Strategy Code: writes strategy
- Strategy Code → Backtest Runner: runs strategy
- Backtest Runner → Market Data: fetches prices
- Backtest Runner → Backtest Validation: validates results
- Backtest Runner → Parameter Scan: scans parameters
- Backtest Runner → Walk Forward: tests out-of-sample
- Backtest Runner → Quality Checks: checks results
- Backtest Runner → Reports: produces report
- Portfolio Manager → Allocation Methods: computes weights
- Portfolio Manager → Position Reconciler: updates targets
- Strategy Code → Strategy Scheduler: scheduled code
- Strategy Scheduler → Position Reconciler: provides targets
- Position Reconciler → Order Execution: requests orders
- Order Execution → Exposure Guard: checks exposure
- Order Execution → Venue Adapters: dispatches orders
- Venue Adapters → Exchanges / Brokers: places orders
- Order Execution → Paper Trading: paper fills
- User → Web / Telegram: sends messages
- Web / Telegram → Cloud Agent Runtime: forwards messages
- Cloud Agent Runtime → Claude / Codex: invokes
- Cloud Agent Runtime → Blave Services: requests data
- Web / Telegram → Telegram: bridges chat
- Web / Telegram → Reports: shows reports