# eranlary/ai_hedge_2 architecture

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

- Interactive diagram: https://gitdiagram.com/eranlary/ai_hedge_2
- Repository: https://github.com/eranlary/ai_hedge_2

## Overview

AI_HEDGE_2 is an equity-research and portfolio platform: a ticker run gathers financial and market research, performs valuation, and produces report artifacts that the web app serves. Other documented product domains include portfolio/research features, release-scoped Nasdaq analysis, LLM-run observability, and isolated IBKR Paper execution. The graph retains these separate domains. Some subsystems are documented but not sampled; their links are included only where the README or indexed references support them.

Main entry points: [`src/ai_hedge/runner.py`](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/runner.py) (Analysis runner), [`frontend/src/app/(app)`](https://github.com/eranlary/ai_hedge_2/tree/main/frontend/src/app/(app)) (Research dashboard), [`src/ai_hedge/db/writer.py`](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/db/writer.py) (Report database), [`src/ai_hedge/cli.py`](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/cli.py) (Local CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Analysis core"]
  node_cli["Local CLI<br/>[cli.py]"]
  node_run_orchestrator["Analysis runner<br/>[runner.py]"]
  node_valuation["Valuation logic<br/>[legacy_port.py]"]
  node_specialist_research["Research agents"]
  node_provider_data["Market data<br/>[yahooquery_data.py]"]
  node_artifact_output["Analysis artifacts<br/>[artifacts.py]"]
  node_report_store[("Report database<br/>[writer.py]")]
end

subgraph group_web["Public research app"]
  node_public_app["Research dashboard"]
  node_web_api["Research API"]
  node_report_views["Reports and filings<br/>[page.tsx]"]
  node_portfolio_features["Portfolio features"]
end

subgraph group_nasdaq["Nasdaq worker"]
  node_nasdaq_api["Nasdaq run control<br/>[route.ts]"]
  node_worker["Analysis worker"]
end

subgraph group_observability["Run observability"]
  node_obs_app["Observability app"]
  node_telemetry["Run telemetry"]
  node_obs_store[("Observability database<br/>[obs-db.ts]")]
end

subgraph group_execution["Paper execution"]
  node_execution_api["Trading control plane"]
  node_executor["Paper execution agent<br/>[engine.py]"]
end

node_researcher(("Research user"))
node_web_user(("Web user"))
node_obs_user(("Admin user"))
node_broker["IB Gateway"]

node_researcher -->|"starts run"| node_cli
node_cli -.->|"dispatches"| node_run_orchestrator
node_run_orchestrator -->|"orchestrates"| node_valuation
node_run_orchestrator -->|"invokes agents"| node_specialist_research
node_run_orchestrator -.->|"uses data"| node_provider_data
node_run_orchestrator -->|"creates artifacts"| node_artifact_output
node_run_orchestrator -->|"writes reports"| node_report_store
node_web_user -->|"views research"| node_public_app
node_public_app -.->|"requests data"| node_web_api
node_web_api -->|"serves reports"| node_report_store
node_public_app -->|"views reports"| node_report_views
node_public_app -->|"tracks portfolios"| node_portfolio_features
node_web_user -.->|"starts analysis"| node_nasdaq_api
node_nasdaq_api -->|"dispatches runs"| node_worker
node_worker -.->|"stores results"| node_report_store
node_run_orchestrator -->|"instruments runs"| node_telemetry
node_obs_user -->|"inspects runs"| node_obs_app
node_obs_app -.->|"reads telemetry"| node_obs_store
node_web_user -.->|"controls trading"| node_execution_api
node_execution_api -.->|"sends commands"| node_executor
node_executor -->|"places orders"| node_broker

click node_cli "https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/cli.py"
click node_run_orchestrator "https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/runner.py"
click node_valuation "https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/legacy_port.py"
click node_specialist_research "https://github.com/eranlary/ai_hedge_2/tree/main/src/ai_hedge"
click node_provider_data "https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/yahooquery_data.py"
click node_artifact_output "https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/io/artifacts.py"
click node_report_store "https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/db/writer.py"
click node_public_app "https://github.com/eranlary/ai_hedge_2/tree/main/frontend/src/app/(app)"
click node_web_api "https://github.com/eranlary/ai_hedge_2/tree/main/frontend/src/app/api"
click node_report_views "https://github.com/eranlary/ai_hedge_2/blob/main/frontend/src/app/(app)/reports/page.tsx"
click node_portfolio_features "https://github.com/eranlary/ai_hedge_2/blob/main/frontend/src/lib/portfolio-performance-engine.ts"
click node_nasdaq_api "https://github.com/eranlary/ai_hedge_2/blob/main/frontend/src/app/api/nasdaq100/runs/route.ts"
click node_worker "https://github.com/eranlary/ai_hedge_2/blob/main/scripts/nasdaq_worker_server.py"
click node_obs_app "https://github.com/eranlary/ai_hedge_2/tree/main/frontend-obs/src/app/(authed)"
click node_telemetry "https://github.com/eranlary/ai_hedge_2/tree/main/src/ai_hedge/obs"
click node_obs_store "https://github.com/eranlary/ai_hedge_2/blob/main/frontend-obs/src/lib/obs-db.ts"
click node_execution_api "https://github.com/eranlary/ai_hedge_2/tree/main/frontend/src/app/api/trading"
click node_executor "https://github.com/eranlary/ai_hedge_2/blob/main/trading_executor/engine.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_run_orchestrator,node_valuation,node_specialist_research,node_provider_data,node_artifact_output,node_report_store,node_researcher,node_web_user,node_obs_user toneBlue
class node_public_app,node_web_api,node_report_views,node_portfolio_features toneAmber
class node_nasdaq_api,node_worker toneMint
class node_obs_app,node_telemetry,node_obs_store toneRose
class node_execution_api,node_executor,node_broker toneIndigo
```

## Components

### Analysis core

- [Local CLI](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/cli.py): `src/ai_hedge/cli.py`
- [Analysis runner](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/runner.py): `src/ai_hedge/runner.py`
- [Valuation logic](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/legacy_port.py): `src/ai_hedge/legacy_port.py`
- [Research agents](https://github.com/eranlary/ai_hedge_2/tree/main/src/ai_hedge): `src/ai_hedge`
- [Market data](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/yahooquery_data.py): `src/ai_hedge/yahooquery_data.py`
- [Analysis artifacts](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/io/artifacts.py): `src/ai_hedge/io/artifacts.py`
- [Report database](https://github.com/eranlary/ai_hedge_2/blob/main/src/ai_hedge/db/writer.py): `src/ai_hedge/db/writer.py`

### Public research app

- [Research dashboard](https://github.com/eranlary/ai_hedge_2/tree/main/frontend/src/app/(app)): `frontend/src/app/(app)`
- [Research API](https://github.com/eranlary/ai_hedge_2/tree/main/frontend/src/app/api): `frontend/src/app/api`
- [Reports and filings](https://github.com/eranlary/ai_hedge_2/blob/main/frontend/src/app/(app)/reports/page.tsx): `frontend/src/app/(app)/reports/page.tsx`
- [Portfolio features](https://github.com/eranlary/ai_hedge_2/blob/main/frontend/src/lib/portfolio-performance-engine.ts): `frontend/src/lib/portfolio-performance-engine.ts`

### Nasdaq worker

- [Nasdaq run control](https://github.com/eranlary/ai_hedge_2/blob/main/frontend/src/app/api/nasdaq100/runs/route.ts): `frontend/src/app/api/nasdaq100/runs/route.ts`
- [Analysis worker](https://github.com/eranlary/ai_hedge_2/blob/main/scripts/nasdaq_worker_server.py): `scripts/nasdaq_worker_server.py`

### Run observability

- [Observability app](https://github.com/eranlary/ai_hedge_2/tree/main/frontend-obs/src/app/(authed)): `frontend-obs/src/app/(authed)`
- [Run telemetry](https://github.com/eranlary/ai_hedge_2/tree/main/src/ai_hedge/obs): `src/ai_hedge/obs`
- [Observability database](https://github.com/eranlary/ai_hedge_2/blob/main/frontend-obs/src/lib/obs-db.ts): `frontend-obs/src/lib/obs-db.ts`

### Paper execution

- [Trading control plane](https://github.com/eranlary/ai_hedge_2/tree/main/frontend/src/app/api/trading): `frontend/src/app/api/trading`
- [Paper execution agent](https://github.com/eranlary/ai_hedge_2/blob/main/trading_executor/engine.py): `trading_executor/engine.py`

### Other components

- **Research user**
- **Web user**
- **Admin user**
- **IB Gateway**

## Connections

- Research user → Local CLI: starts run (evidence: `README.md`)
- Local CLI → Analysis runner: dispatches
- Analysis runner → Valuation logic: orchestrates (evidence: `src/ai_hedge/runner.py`)
- Analysis runner → Research agents: invokes agents (evidence: `src/ai_hedge/runner.py`)
- Analysis runner → Market data: uses data
- Analysis runner → Analysis artifacts: creates artifacts (evidence: `README.md`)
- Analysis runner → Report database: writes reports (evidence: `README.md`)
- Web user → Research dashboard: views research (evidence: `README.md`)
- Research dashboard → Research API: requests data
- Research API → Report database: serves reports (evidence: `README.md`)
- Research dashboard → Reports and filings: views reports (evidence: `README.md`)
- Research dashboard → Portfolio features: tracks portfolios (evidence: `README.md`)
- Web user → Nasdaq run control: starts analysis
- Nasdaq run control → Analysis worker: dispatches runs (evidence: `README.md`)
- Analysis worker → Report database: stores results
- Analysis runner → Run telemetry: instruments runs (evidence: `README.md`)
- Admin user → Observability app: inspects runs (evidence: `README.md`)
- Observability app → Observability database: reads telemetry
- Web user → Trading control plane: controls trading
- Trading control plane → Paper execution agent: sends commands
- Paper execution agent → IB Gateway: places orders (evidence: `README.md`)