# ihsieh31/traders architecture

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

- Interactive diagram: https://gitdiagram.com/ihsieh31/traders
- Repository: https://github.com/ihsieh31/traders

## Overview

Traders is a paper-only, multi-agent trading research and execution framework. A user starts an analysis or observation; market evidence feeds screening and role-based research, debate, and a typed TradeIntent. Deterministic risk and safety checks precede the durable paper-execution boundary, with broker state and audit records supporting recovery and review. The README also documents long-run observation, a frozen-evidence A/B backend, and signal backtesting. Edges reflect the documented workflow; sampled source was incomplete, so uncertain internal wiring is omitted.

Main entry points: [`tradingagents/graph/trading_graph.py`](https://github.com/ihsieh31/traders/blob/main/tradingagents/graph/trading_graph.py) (Research graph), [`tradingagents/llm_clients/factory.py`](https://github.com/ihsieh31/traders/blob/main/tradingagents/llm_clients/factory.py) (LLM providers), [`tradingagents/execution/service.py`](https://github.com/ihsieh31/traders/blob/main/tradingagents/execution/service.py) (Execution service), [`tradingagents/screening/pipeline.py`](https://github.com/ihsieh31/traders/blob/main/tradingagents/screening/pipeline.py) (Screening)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research workflow"]
  node_screening["Screening<br/>[pipeline.py]"]
  node_selection[("Selection cache<br/>[selection_store.py]")]
  node_workflow["Research graph<br/>[trading_graph.py]"]
  node_analysts["Analyst roles"]
  node_researchers["Bull/Bear researchers"]
  node_research_manager["Research manager"]
  node_trader["Trader proposal<br/>[trader.py]"]
  node_risk_debate["Risk debate"]
  node_risk_manager["Risk manager<br/>[risk_manager.py]"]
  node_intent["Typed TradeIntent<br/>[schemas.py]"]
end

subgraph group_execution["Paper execution"]
  node_guards["Risk and safety"]
  node_service["Execution service<br/>[service.py]"]
  node_ledger[("Execution ledger<br/>[store.py]")]
end

subgraph group_operations["Observation and audit"]
  node_audit[("Run audit<br/>[run_logger.py]")]
  node_longrun["Long-run lifecycle<br/>[long_run.py]"]
end

subgraph group_integrations["External integrations"]
  node_marketdata["Market data"]
  node_alpaca["Alpaca Paper"]
  node_historical_bars["Historical bars"]
  node_llm["LLM providers<br/>[factory.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_berkshire["Berkshire backend"]
  node_ab_runner["A/B runner<br/>[run_analysis_ab.py]"]
  node_backtest["Signal backtest<br/>[engine.py]"]
end

node_user(("Operator"))
node_cli["CLI<br/>[main.py]"]

node_user -->|"starts run"| node_cli
node_cli -->|"runs analysis"| node_workflow
node_cli -->|"starts scan"| node_screening
node_marketdata -->|"supplies market data"| node_screening
node_screening -->|"stores selection"| node_selection
node_selection -->|"reuses selection"| node_screening
node_screening -->|"selects symbols"| node_workflow
node_workflow -->|"requests evidence"| node_marketdata
node_workflow -->|"dispatches analysis"| node_analysts
node_analysts -->|"requests analysis"| node_llm
node_workflow -->|"dispatches debate"| node_researchers
node_researchers -->|"requests research"| node_llm
node_workflow -->|"dispatches adjudication"| node_research_manager
node_research_manager -->|"requests plan"| node_llm
node_workflow -->|"requests proposal"| node_trader
node_trader -->|"requests proposal"| node_llm
node_workflow -->|"dispatches risk debate"| node_risk_debate
node_risk_debate -->|"requests debate"| node_llm
node_workflow -->|"dispatches decision"| node_risk_manager
node_risk_manager -->|"requests decision"| node_llm
node_risk_manager -->|"builds intent"| node_intent
node_intent -->|"checked by"| node_guards
node_guards -->|"permits execution"| node_service
node_service -->|"commits intent"| node_ledger
node_service -->|"submits paper orders"| node_alpaca
node_alpaca -->|"returns broker state"| node_service
node_service -->|"records outcome"| node_audit
node_cli -->|"starts observation"| node_longrun
node_longrun -->|"runs rounds"| node_workflow
node_ab_runner -->|"runs Traders backend"| node_workflow
node_ab_runner -->|"runs comparison backend"| node_berkshire
node_historical_bars -->|"provides bars"| node_backtest
node_backtest -->|"replays signals"| node_historical_bars

click node_cli "https://github.com/ihsieh31/traders/blob/main/cli/main.py"
click node_screening "https://github.com/ihsieh31/traders/blob/main/tradingagents/screening/pipeline.py"
click node_selection "https://github.com/ihsieh31/traders/blob/main/tradingagents/screening/selection_store.py"
click node_marketdata "https://github.com/ihsieh31/traders/tree/main/tradingagents/dataflows"
click node_workflow "https://github.com/ihsieh31/traders/blob/main/tradingagents/graph/trading_graph.py"
click node_analysts "https://github.com/ihsieh31/traders/tree/main/tradingagents/agents/analysts"
click node_researchers "https://github.com/ihsieh31/traders/tree/main/tradingagents/agents/researchers"
click node_research_manager "https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/managers/research_manager.py"
click node_trader "https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/trader/trader.py"
click node_risk_debate "https://github.com/ihsieh31/traders/tree/main/tradingagents/agents/risk_mgmt"
click node_risk_manager "https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/managers/risk_manager.py"
click node_intent "https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/schemas.py"
click node_guards "https://github.com/ihsieh31/traders/tree/main/tradingagents/risk"
click node_service "https://github.com/ihsieh31/traders/blob/main/tradingagents/execution/service.py"
click node_ledger "https://github.com/ihsieh31/traders/blob/main/tradingagents/execution/store.py"
click node_audit "https://github.com/ihsieh31/traders/blob/main/tradingagents/run_logger.py"
click node_longrun "https://github.com/ihsieh31/traders/blob/main/tradingagents/long_run.py"
click node_berkshire "https://github.com/ihsieh31/traders/tree/main/tradingagents/analysis_backends/berkshire"
click node_ab_runner "https://github.com/ihsieh31/traders/blob/main/scripts/run_analysis_ab.py"
click node_backtest "https://github.com/ihsieh31/traders/blob/main/tradingagents/backtest/engine.py"
click node_llm "https://github.com/ihsieh31/traders/blob/main/tradingagents/llm_clients/factory.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_screening,node_selection,node_workflow,node_analysts,node_researchers,node_research_manager,node_trader,node_risk_debate,node_risk_manager,node_intent toneBlue
class node_guards,node_service,node_ledger toneAmber
class node_audit,node_longrun toneMint
class node_marketdata,node_alpaca,node_historical_bars,node_llm toneRose
class node_berkshire,node_ab_runner,node_backtest,node_user toneIndigo
class node_cli toneTeal
```

## Components

### Research workflow

- [Screening](https://github.com/ihsieh31/traders/blob/main/tradingagents/screening/pipeline.py): `tradingagents/screening/pipeline.py`
- [Selection cache](https://github.com/ihsieh31/traders/blob/main/tradingagents/screening/selection_store.py): `tradingagents/screening/selection_store.py`
- [Research graph](https://github.com/ihsieh31/traders/blob/main/tradingagents/graph/trading_graph.py): `tradingagents/graph/trading_graph.py`
- [Analyst roles](https://github.com/ihsieh31/traders/tree/main/tradingagents/agents/analysts): `tradingagents/agents/analysts`
- [Bull/Bear researchers](https://github.com/ihsieh31/traders/tree/main/tradingagents/agents/researchers): `tradingagents/agents/researchers`
- [Research manager](https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/managers/research_manager.py): `tradingagents/agents/managers/research_manager.py`
- [Trader proposal](https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/trader/trader.py): `tradingagents/agents/trader/trader.py`
- [Risk debate](https://github.com/ihsieh31/traders/tree/main/tradingagents/agents/risk_mgmt): `tradingagents/agents/risk_mgmt`
- [Risk manager](https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/managers/risk_manager.py): `tradingagents/agents/managers/risk_manager.py`
- [Typed TradeIntent](https://github.com/ihsieh31/traders/blob/main/tradingagents/agents/schemas.py): `tradingagents/agents/schemas.py`

### Paper execution

- [Risk and safety](https://github.com/ihsieh31/traders/tree/main/tradingagents/risk): `tradingagents/risk`
- [Execution service](https://github.com/ihsieh31/traders/blob/main/tradingagents/execution/service.py): `tradingagents/execution/service.py`
- [Execution ledger](https://github.com/ihsieh31/traders/blob/main/tradingagents/execution/store.py): `tradingagents/execution/store.py`

### Observation and audit

- [Run audit](https://github.com/ihsieh31/traders/blob/main/tradingagents/run_logger.py): `tradingagents/run_logger.py`
- [Long-run lifecycle](https://github.com/ihsieh31/traders/blob/main/tradingagents/long_run.py): `tradingagents/long_run.py`

### External integrations

- [Market data](https://github.com/ihsieh31/traders/tree/main/tradingagents/dataflows): `tradingagents/dataflows`
- **Alpaca Paper**
- **Historical bars**
- [LLM providers](https://github.com/ihsieh31/traders/blob/main/tradingagents/llm_clients/factory.py): `tradingagents/llm_clients/factory.py`

### Evaluation

- [Berkshire backend](https://github.com/ihsieh31/traders/tree/main/tradingagents/analysis_backends/berkshire): `tradingagents/analysis_backends/berkshire`
- [A/B runner](https://github.com/ihsieh31/traders/blob/main/scripts/run_analysis_ab.py): `scripts/run_analysis_ab.py`
- [Signal backtest](https://github.com/ihsieh31/traders/blob/main/tradingagents/backtest/engine.py): `tradingagents/backtest/engine.py`

### Other components

- **Operator**
- [CLI](https://github.com/ihsieh31/traders/blob/main/cli/main.py): `cli/main.py`

## Connections

- Operator → CLI: starts run
- CLI → Research graph: runs analysis
- CLI → Screening: starts scan
- Market data → Screening: supplies market data
- Screening → Selection cache: stores selection
- Selection cache → Screening: reuses selection
- Screening → Research graph: selects symbols
- Research graph → Market data: requests evidence
- Research graph → Analyst roles: dispatches analysis
- Analyst roles → LLM providers: requests analysis
- Research graph → Bull/Bear researchers: dispatches debate
- Bull/Bear researchers → LLM providers: requests research
- Research graph → Research manager: dispatches adjudication
- Research manager → LLM providers: requests plan
- Research graph → Trader proposal: requests proposal
- Trader proposal → LLM providers: requests proposal
- Research graph → Risk debate: dispatches risk debate
- Risk debate → LLM providers: requests debate
- Research graph → Risk manager: dispatches decision
- Risk manager → LLM providers: requests decision
- Risk manager → Typed TradeIntent: builds intent
- Typed TradeIntent → Risk and safety: checked by
- Risk and safety → Execution service: permits execution
- Execution service → Execution ledger: commits intent
- Execution service → Alpaca Paper: submits paper orders
- Alpaca Paper → Execution service: returns broker state
- Execution service → Run audit: records outcome
- CLI → Long-run lifecycle: starts observation
- Long-run lifecycle → Research graph: runs rounds
- A/B runner → Research graph: runs Traders backend
- A/B runner → Berkshire backend: runs comparison backend
- Historical bars → Signal backtest: provides bars
- Signal backtest → Historical bars: replays signals