# shreyasg13/glassbox-trading-agents architecture

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

- Interactive diagram: https://gitdiagram.com/shreyasg13/glassbox-trading-agents
- Repository: https://github.com/shreyasg13/glassbox-trading-agents

## Overview

GlassBox is a web platform for evidence-first stock research and simulated paper trading, not an order-execution system. Users explore committee signals, portfolios, comparisons and reports in the Next.js app; the FastAPI API serves those views and administrative controls. The documented daily workflow waits for finalized market prices, refreshes data, runs the committee and paper accounts, then produces research and reporting outputs. The graph includes documented capabilities whose implementation was not sampled; their internal wiring is shown only where supported by the README or excerpts.

Main entry points: [`backend/app/routers`](https://github.com/shreyasg13/glassbox-trading-agents/tree/main/backend/app/routers) (HTTP routers), [`backend/app/committee_graph.py`](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/committee_graph.py) (Investment committee), [`backend/app/pipeline.py`](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/pipeline.py) (Daily pipeline), [`backend/app/paper_cycle.py`](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/paper_cycle.py) (Paper accounts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_frontend["Next.js app<br/>[page.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_admin_ui["Admin console<br/>[ResearchPanel.tsx]"]
end

subgraph group_api["API and jobs"]
  node_fastapi["FastAPI gateway<br/>[main.py]"]
  node_routers["HTTP routers"]
  node_daily_pipeline["Daily pipeline<br/>[pipeline.py]"]
end

subgraph group_research["Research and data"]
  node_committee["Investment committee<br/>[committee_graph.py]"]
  node_research_data["Research and filings<br/>[research.py]"]
  node_data_sources["Market data sync<br/>[data_source.py]"]
  node_free_data["Free public data<br/>[free_data.py]"]
  node_llm_router["LLM failover<br/>[llm_router.py]"]
  node_providers["Model providers<br/>[factory.py]"]
end

subgraph group_simulation["Simulation and evidence"]
  node_paper["Paper accounts<br/>[paper_cycle.py]"]
  node_strategy["Quant baselines<br/>[strategy.py]"]
  node_risk["Risk checks<br/>[risk.py]"]
  node_portfolio["Portfolio views<br/>[portfolio_view.py]"]
  node_evidence["Evidence gate<br/>[research.py]"]
  node_arena["Challenger arena<br/>[arena.py]"]
  node_reports["Reports and digests<br/>[digest.py]"]
end

subgraph group_platform["Identity and integrations"]
  node_database[("Application storage<br/>[db.py]")]
  node_auth["Authentication<br/>[auth.py]"]
  node_oauth_provider["Google OAuth<br/>[oauth_google.py]"]
  node_tts["Speech generation<br/>[tts.py]"]
end

node_user(("Investor or admin"))
node_market_provider{{"Market data provider"}}
node_llm_service{{"LLM services"}}
node_google{{"Google identity"}}
node_email{{"Email delivery"}}

node_user -->|"uses"| node_frontend
node_frontend -->|"requests data"| node_frontend_api
node_admin_ui -->|"requests data"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_fastapi
node_fastapi -->|"dispatches routes"| node_routers
node_routers -->|"reads and writes"| node_database
node_routers -->|"runs analysis"| node_committee
node_routers -->|"serves portfolio"| node_portfolio
node_routers -->|"serves evidence"| node_evidence
node_routers -->|"records calls"| node_arena
node_routers -->|"serves reports"| node_reports
node_daily_pipeline -->|"syncs prices"| node_data_sources
node_daily_pipeline -->|"refreshes data"| node_free_data
node_daily_pipeline -->|"runs committee"| node_committee
node_daily_pipeline -->|"runs paper cycle"| node_paper
node_daily_pipeline -->|"creates digests"| node_reports
node_data_sources -->|"fetches prices"| node_market_provider
node_free_data -.->|"fetches filings"| node_market_provider
node_committee -->|"uses research"| node_research_data
node_committee -->|"checks calls"| node_risk
node_committee -->|"requests completion"| node_llm_router
node_llm_router -->|"selects provider"| node_providers
node_providers -.->|"sends prompts"| node_llm_service
node_paper -->|"uses calls"| node_committee
node_paper -->|"compares baselines"| node_strategy
node_paper -->|"persists results"| node_database
node_evidence -->|"reads scored history"| node_database
node_arena -->|"scores challengers"| node_paper
node_reports -.->|"sends digests"| node_email
node_routers -->|"checks identity"| node_auth
node_auth -->|"reads identity"| node_database
node_routers -->|"starts OAuth"| node_oauth_provider
node_oauth_provider -->|"exchanges code"| node_google
node_frontend -.->|"requests speech"| node_tts
node_tts -.->|"generates audio"| node_llm_service

click node_frontend "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/frontend/app/(app)/dashboard/page.tsx"
click node_frontend_api "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/frontend/lib/api.ts"
click node_admin_ui "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/frontend/components/admin/strategy/ResearchPanel.tsx"
click node_fastapi "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/main.py"
click node_routers "https://github.com/shreyasg13/glassbox-trading-agents/tree/main/backend/app/routers"
click node_daily_pipeline "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/pipeline.py"
click node_committee "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/committee_graph.py"
click node_research_data "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/research.py"
click node_data_sources "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/data_source.py"
click node_free_data "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/free_data.py"
click node_llm_router "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/llm_router.py"
click node_providers "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/providers/factory.py"
click node_paper "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/paper_cycle.py"
click node_strategy "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/strategy.py"
click node_risk "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/risk.py"
click node_portfolio "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/portfolio_view.py"
click node_evidence "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/research.py"
click node_arena "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/arena.py"
click node_reports "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/digest.py"
click node_database "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/db.py"
click node_auth "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/auth.py"
click node_oauth_provider "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/oauth_google.py"
click node_tts "https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/tts.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_frontend,node_frontend_api,node_admin_ui toneBlue
class node_fastapi,node_routers,node_daily_pipeline toneAmber
class node_committee,node_research_data,node_data_sources,node_free_data,node_llm_router,node_providers toneMint
class node_paper,node_strategy,node_risk,node_portfolio,node_evidence,node_arena,node_reports toneRose
class node_database,node_auth,node_oauth_provider,node_tts,node_user,node_market_provider,node_llm_service,node_google,node_email toneIndigo
```

## Components

### Web experience

- [Next.js app](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/frontend/app/(app)/dashboard/page.tsx): `frontend/app/(app)/dashboard/page.tsx`
- [API client](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Admin console](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/frontend/components/admin/strategy/ResearchPanel.tsx): `frontend/components/admin/strategy/ResearchPanel.tsx`

### API and jobs

- [FastAPI gateway](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/main.py): `backend/app/main.py`
- [HTTP routers](https://github.com/shreyasg13/glassbox-trading-agents/tree/main/backend/app/routers): `backend/app/routers`
- [Daily pipeline](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/pipeline.py): `backend/app/pipeline.py`

### Research and data

- [Investment committee](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/committee_graph.py): `backend/app/committee_graph.py`
- [Research and filings](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/research.py): `backend/app/research.py`
- [Market data sync](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/data_source.py): `backend/app/data_source.py`
- [Free public data](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/free_data.py): `backend/app/free_data.py`
- [LLM failover](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/llm_router.py): `backend/app/llm_router.py`
- [Model providers](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/providers/factory.py): `backend/app/providers/factory.py`

### Simulation and evidence

- [Paper accounts](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/paper_cycle.py): `backend/app/paper_cycle.py`
- [Quant baselines](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/strategy.py): `backend/app/strategy.py`
- [Risk checks](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/risk.py): `backend/app/risk.py`
- [Portfolio views](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/portfolio_view.py): `backend/app/portfolio_view.py`
- [Evidence gate](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/research.py): `backend/app/research.py`
- [Challenger arena](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/arena.py): `backend/app/arena.py`
- [Reports and digests](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/digest.py): `backend/app/digest.py`

### Identity and integrations

- [Application storage](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/db.py): `backend/app/db.py`
- [Authentication](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Google OAuth](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/oauth_google.py): `backend/app/oauth_google.py`
- [Speech generation](https://github.com/shreyasg13/glassbox-trading-agents/blob/main/backend/app/tts.py): `backend/app/tts.py`

### Other components

- **Investor or admin**
- **Market data provider**
- **LLM services**
- **Google identity**
- **Email delivery**

## Connections

- Investor or admin → Next.js app: uses
- Next.js app → API client: requests data
- Admin console → API client: requests data
- API client → FastAPI gateway: HTTP requests
- FastAPI gateway → HTTP routers: dispatches routes
- HTTP routers → Application storage: reads and writes
- HTTP routers → Investment committee: runs analysis
- HTTP routers → Portfolio views: serves portfolio
- HTTP routers → Evidence gate: serves evidence
- HTTP routers → Challenger arena: records calls
- HTTP routers → Reports and digests: serves reports
- Daily pipeline → Market data sync: syncs prices
- Daily pipeline → Free public data: refreshes data
- Daily pipeline → Investment committee: runs committee
- Daily pipeline → Paper accounts: runs paper cycle
- Daily pipeline → Reports and digests: creates digests
- Market data sync → Market data provider: fetches prices
- Free public data → Market data provider: fetches filings
- Investment committee → Research and filings: uses research
- Investment committee → Risk checks: checks calls
- Investment committee → LLM failover: requests completion
- LLM failover → Model providers: selects provider
- Model providers → LLM services: sends prompts
- Paper accounts → Investment committee: uses calls
- Paper accounts → Quant baselines: compares baselines
- Paper accounts → Application storage: persists results
- Evidence gate → Application storage: reads scored history
- Challenger arena → Paper accounts: scores challengers
- Reports and digests → Email delivery: sends digests
- HTTP routers → Authentication: checks identity
- Authentication → Application storage: reads identity
- HTTP routers → Google OAuth: starts OAuth
- Google OAuth → Google identity: exchanges code
- Next.js app → Speech generation: requests speech
- Speech generation → LLM services: generates audio