# edison-vs-tesla/ai-hedge-fund architecture

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

- Interactive diagram: https://gitdiagram.com/edison-vs-tesla/ai-hedge-fund
- Repository: https://github.com/edison-vs-tesla/ai-hedge-fund

## Overview

This repository combines an LLM-driven equity analysis and trading system with a visual flow-building web app. The primary trading workflow runs analyst signals through risk sizing and portfolio decisions, then optionally executes through a broker; the daemon adds price-driven watch and escalation stages. Separate capabilities include historical backtesting, quant research, and universe selection. The graph follows README-documented integration points and the sampled workflow code; unsampled service internals are represented only where paths are supported, and uncertain wiring is omitted.

Main entry points: [`integrations/alpaca/run_cycle.py`](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/run_cycle.py) (Trading cycle), [`src/main.py`](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/main.py) (Agent workflow), [`integrations/alpaca/scheduler.py`](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/scheduler.py) (Trading daemon), [`app/backend/routes/flows.py`](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/routes/flows.py) (Flow routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trading["Trading runtime"]
  node_cli["Alpaca CLI<br/>[cli.py]"]
  node_scheduler["Trading daemon<br/>[scheduler.py]"]
  node_cycle["Trading cycle<br/>[run_cycle.py]"]
  node_light["Light cycle<br/>[light_cycle.py]"]
  node_signals["Analyst agents"]
  node_workflow["Agent workflow<br/>[main.py]"]
  node_risk["Risk sizing<br/>[risk_manager.py]"]
  node_manager["Portfolio decisions"]
end

subgraph group_market["Market integrations"]
  node_broker_api["Broker protocol<br/>[protocol.py]"]
  node_alpaca_broker["Alpaca broker<br/>[broker.py]"]
  node_data_stack["Composite data<br/>[composite.py]"]
  node_data_bridge["Data API bridge<br/>[v1_bridge.py]"]
  node_market_services["Market providers"]
  node_ledger[("Cycle ledger<br/>[ledger.py]")]
  node_session_state[("Scheduler state<br/>[session.py]")]
end

subgraph group_research["Research tools"]
  node_legacy_backtest["Agent backtesting<br/>[engine.py]"]
  node_quant_stack["PEAD quant stack<br/>[pead.py]"]
  node_quant_backtest["Quant backtesting<br/>[engine.py]"]
  node_event_study["Earnings event study<br/>[engine.py]"]
  node_universe["Universe builder<br/>[pipeline.py]"]
end

subgraph group_web["Flow web app"]
  node_flow_editor["Flow editor<br/>[Flow.tsx]"]
  node_web_api["Frontend API<br/>[api.ts]"]
end

subgraph group_backend["Web backend"]
  node_api_server["Backend API<br/>[main.py]"]
  node_flow_routes["Flow routes<br/>[flows.py]"]
  node_flow_store["Flow repository<br/>[flow_repository.py]"]
  node_app_database[("Application database<br/>[connection.py]")]
  node_app_agents["Flow agent service<br/>[agent_service.py]"]
  node_backtest_service["Backtest service"]
end

node_trader(("Trader"))
node_web_user(("Web user"))

node_trader -->|"invokes"| node_cli
node_cli -->|"starts daemon"| node_scheduler
node_cli -->|"runs cycle"| node_cycle
node_scheduler -->|"escalates"| node_light
node_scheduler -->|"runs heavy cycle"| node_cycle
node_cycle -->|"runs agents"| node_workflow
node_workflow -->|"dispatches"| node_signals
node_workflow -->|"dispatches"| node_risk
node_risk -->|"passes limits"| node_manager
node_workflow -->|"dispatches"| node_manager
node_risk -->|"fetches prices"| node_data_bridge
node_data_bridge -->|"requests data"| node_data_stack
node_data_stack -->|"fetches market data"| node_market_services
node_cycle -->|"submits trades"| node_broker_api
node_broker_api -->|"dispatches"| node_alpaca_broker
node_cycle -->|"records cycle"| node_ledger
node_scheduler -->|"tracks session"| node_session_state
node_trader -->|"runs backtest"| node_legacy_backtest
node_legacy_backtest -->|"runs daily analysis"| node_workflow
node_quant_backtest -->|"queries signals"| node_quant_stack
node_event_study -.->|"requests prices"| node_market_services
node_universe -->|"enriches candidates"| node_market_services
node_web_user -->|"edits flows"| node_flow_editor
node_flow_editor -->|"requests operations"| node_web_api
node_web_api -->|"sends requests"| node_api_server
node_api_server -->|"dispatches"| node_flow_routes
node_flow_routes -->|"reads and writes"| node_flow_store
node_flow_store -->|"persists flows"| node_app_database
node_flow_routes -->|"invokes"| node_app_agents
node_flow_routes -->|"invokes"| node_backtest_service

click node_cli "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/cli.py"
click node_scheduler "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/scheduler.py"
click node_cycle "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/run_cycle.py"
click node_light "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/light_cycle.py"
click node_signals "https://github.com/edison-vs-tesla/ai-hedge-fund/tree/main/src/agents"
click node_workflow "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/main.py"
click node_risk "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/agents/risk_manager.py"
click node_manager "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/agents/portfolio_manager.py"
click node_broker_api "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/broker/protocol.py"
click node_alpaca_broker "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/broker.py"
click node_data_stack "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/data/composite.py"
click node_data_bridge "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/data/v1_bridge.py"
click node_ledger "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/ledger.py"
click node_session_state "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/session.py"
click node_legacy_backtest "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/backtesting/engine.py"
click node_quant_stack "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/v2/signals/pead.py"
click node_quant_backtest "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/v2/backtesting/engine.py"
click node_event_study "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/v2/event_study/engine.py"
click node_universe "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/universe/pipeline.py"
click node_flow_editor "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/frontend/src/components/Flow.tsx"
click node_web_api "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/frontend/src/services/api.ts"
click node_api_server "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/main.py"
click node_flow_routes "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/routes/flows.py"
click node_flow_store "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/repositories/flow_repository.py"
click node_app_database "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/database/connection.py"
click node_app_agents "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/services/agent_service.py"
click node_backtest_service "https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/services/backtest_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_cli,node_scheduler,node_cycle,node_light,node_signals,node_workflow,node_risk,node_manager,node_web_user toneBlue
class node_broker_api,node_alpaca_broker,node_data_stack,node_data_bridge,node_market_services,node_ledger,node_session_state toneAmber
class node_legacy_backtest,node_quant_stack,node_quant_backtest,node_event_study,node_universe toneMint
class node_flow_editor,node_web_api toneRose
class node_api_server,node_flow_routes,node_flow_store,node_app_database,node_app_agents,node_backtest_service,node_trader toneIndigo
```

## Components

### Trading runtime

- [Alpaca CLI](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/cli.py): `integrations/alpaca/cli.py`
- [Trading daemon](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/scheduler.py): `integrations/alpaca/scheduler.py`
- [Trading cycle](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/run_cycle.py): `integrations/alpaca/run_cycle.py`
- [Light cycle](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/light_cycle.py): `integrations/alpaca/light_cycle.py`
- [Analyst agents](https://github.com/edison-vs-tesla/ai-hedge-fund/tree/main/src/agents): `src/agents`
- [Agent workflow](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/main.py): `src/main.py`
- [Risk sizing](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/agents/risk_manager.py): `src/agents/risk_manager.py`
- [Portfolio decisions](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/agents/portfolio_manager.py): `src/agents/portfolio_manager.py`

### Market integrations

- [Broker protocol](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/broker/protocol.py): `integrations/broker/protocol.py`
- [Alpaca broker](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/broker.py): `integrations/alpaca/broker.py`
- [Composite data](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/data/composite.py): `integrations/data/composite.py`
- [Data API bridge](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/data/v1_bridge.py): `integrations/data/v1_bridge.py`
- **Market providers**
- [Cycle ledger](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/ledger.py): `integrations/alpaca/ledger.py`
- [Scheduler state](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/alpaca/session.py): `integrations/alpaca/session.py`

### Research tools

- [Agent backtesting](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/src/backtesting/engine.py): `src/backtesting/engine.py`
- [PEAD quant stack](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/v2/signals/pead.py): `v2/signals/pead.py`
- [Quant backtesting](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/v2/backtesting/engine.py): `v2/backtesting/engine.py`
- [Earnings event study](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/v2/event_study/engine.py): `v2/event_study/engine.py`
- [Universe builder](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/integrations/universe/pipeline.py): `integrations/universe/pipeline.py`

### Flow web app

- [Flow editor](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/frontend/src/components/Flow.tsx): `app/frontend/src/components/Flow.tsx`
- [Frontend API](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/frontend/src/services/api.ts): `app/frontend/src/services/api.ts`

### Web backend

- [Backend API](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/main.py): `app/backend/main.py`
- [Flow routes](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/routes/flows.py): `app/backend/routes/flows.py`
- [Flow repository](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/repositories/flow_repository.py): `app/backend/repositories/flow_repository.py`
- [Application database](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/database/connection.py): `app/backend/database/connection.py`
- [Flow agent service](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/services/agent_service.py): `app/backend/services/agent_service.py`
- [Backtest service](https://github.com/edison-vs-tesla/ai-hedge-fund/blob/main/app/backend/services/backtest_service.py): `app/backend/services/backtest_service.py`

### Other components

- **Trader**
- **Web user**

## Connections

- Trader → Alpaca CLI: invokes
- Alpaca CLI → Trading daemon: starts daemon
- Alpaca CLI → Trading cycle: runs cycle
- Trading daemon → Light cycle: escalates
- Trading daemon → Trading cycle: runs heavy cycle
- Trading cycle → Agent workflow: runs agents
- Agent workflow → Analyst agents: dispatches
- Agent workflow → Risk sizing: dispatches
- Risk sizing → Portfolio decisions: passes limits
- Agent workflow → Portfolio decisions: dispatches
- Risk sizing → Data API bridge: fetches prices
- Data API bridge → Composite data: requests data
- Composite data → Market providers: fetches market data
- Trading cycle → Broker protocol: submits trades
- Broker protocol → Alpaca broker: dispatches
- Trading cycle → Cycle ledger: records cycle
- Trading daemon → Scheduler state: tracks session
- Trader → Agent backtesting: runs backtest
- Agent backtesting → Agent workflow: runs daily analysis
- Quant backtesting → PEAD quant stack: queries signals
- Earnings event study → Market providers: requests prices
- Universe builder → Market providers: enriches candidates
- Web user → Flow editor: edits flows
- Flow editor → Frontend API: requests operations
- Frontend API → Backend API: sends requests
- Backend API → Flow routes: dispatches
- Flow routes → Flow repository: reads and writes
- Flow repository → Application database: persists flows
- Flow routes → Flow agent service: invokes
- Flow routes → Backtest service: invokes