# krupashetty004/ai-trading-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/krupashetty004/ai-trading-simulator
- Repository: https://github.com/krupashetty004/ai-trading-simulator

## Overview

THESIS is a browser-based historical trading decision simulator, not a broker or live-trading system. A user reviews a market snapshot, records a decision passport, sees a model-assisted brief and independent risk checks, then can save a simulated trade for later portfolio and outcome review. The graph preserves the separately documented market-evidence, model-reasoning, behavioral-clearance, and audit capabilities. Backend internals are represented only at the documented API boundary; the available excerpts do not show their implementation details.

Main entry points: [`src/App.tsx`](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/App.tsx) (Workspace navigation), [`src/pages/Trading.tsx`](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Trading.tsx) (Trade simulator), [`src/context/PortfolioContext.tsx`](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/context/PortfolioContext.tsx) (Simulation ledger), [`server.ts`](https://github.com/krupashetty004/ai-trading-simulator/blob/main/server.ts) (Analysis API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Application experience"]
  node_entry["React entry<br/>[main.tsx]"]
  node_app["Workspace navigation<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_methodology["Methodology<br/>[Methodology.tsx]"]
  node_theme["Theme state<br/>[ThemeContext.tsx]"]
end

subgraph group_decision["Decision workflow"]
  node_trading["Trade simulator<br/>[Trading.tsx]"]
  node_chart["Historical chart"]
  node_risk["Behavioral risk guard<br/>[riskGuard.ts]"]
  node_analysis["Research brief<br/>[AIAnalysis.tsx]"]
end

subgraph group_state["Portfolio and audit"]
  node_portfolio["Portfolio review<br/>[Portfolio.tsx]"]
  node_ledger[("Simulation ledger")]
  node_domain["Decision data types<br/>[types.ts]"]
end

subgraph group_services["Analysis services"]
  node_api["Analysis API<br/>[server.ts]"]
  node_worker["Worker runtime<br/>[worker.ts]"]
end

node_user(("Retail trader"))
node_market["Yahoo Finance"]
node_gemini["Google Gemini"]
node_browserstore[("Browser local storage")]

node_user -->|"uses"| node_app
node_entry -->|"renders"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_trading
node_app -->|"routes to"| node_portfolio
node_app -->|"routes to"| node_analysis
node_app -->|"routes to"| node_methodology
node_app -->|"provides"| node_theme
node_trading -->|"renders"| node_chart
node_trading -->|"evaluates"| node_risk
node_trading -->|"requests analysis"| node_api
node_analysis -->|"requests analysis"| node_api
node_trading -->|"reads portfolio"| node_ledger
node_trading -->|"records simulation"| node_ledger
node_dashboard -->|"reads portfolio"| node_ledger
node_portfolio -->|"reads ledger"| node_ledger
node_ledger -->|"persists to"| node_browserstore
node_ledger -->|"uses types"| node_domain
node_api -->|"fetches history and news"| node_market
node_api -->|"requests reasoning"| node_gemini

click node_entry "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/main.tsx"
click node_app "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/App.tsx"
click node_dashboard "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Dashboard.tsx"
click node_methodology "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Methodology.tsx"
click node_theme "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/context/ThemeContext.tsx"
click node_trading "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Trading.tsx"
click node_chart "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/components/CandlestickChart.tsx"
click node_risk "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/utils/riskGuard.ts"
click node_analysis "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/AIAnalysis.tsx"
click node_portfolio "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Portfolio.tsx"
click node_ledger "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/context/PortfolioContext.tsx"
click node_domain "https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/types.ts"
click node_api "https://github.com/krupashetty004/ai-trading-simulator/blob/main/server.ts"
click node_worker "https://github.com/krupashetty004/ai-trading-simulator/blob/main/worker.ts"

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_entry,node_app,node_dashboard,node_methodology,node_theme toneBlue
class node_trading,node_chart,node_risk,node_analysis,node_browserstore toneAmber
class node_portfolio,node_ledger,node_domain toneMint
class node_api,node_worker toneRose
class node_user,node_market,node_gemini toneIndigo
```

## Components

### Application experience

- [React entry](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/main.tsx): `src/main.tsx`
- [Workspace navigation](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/App.tsx): `src/App.tsx`
- [Dashboard](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Dashboard.tsx): `src/pages/Dashboard.tsx`
- [Methodology](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Methodology.tsx): `src/pages/Methodology.tsx`
- [Theme state](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/context/ThemeContext.tsx): `src/context/ThemeContext.tsx`

### Decision workflow

- [Trade simulator](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Trading.tsx): `src/pages/Trading.tsx`
- [Historical chart](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/components/CandlestickChart.tsx): `src/components/CandlestickChart.tsx`
- [Behavioral risk guard](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/utils/riskGuard.ts): `src/utils/riskGuard.ts`
- [Research brief](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/AIAnalysis.tsx): `src/pages/AIAnalysis.tsx`

### Portfolio and audit

- [Portfolio review](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/pages/Portfolio.tsx): `src/pages/Portfolio.tsx`
- [Simulation ledger](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/context/PortfolioContext.tsx): `src/context/PortfolioContext.tsx`
- [Decision data types](https://github.com/krupashetty004/ai-trading-simulator/blob/main/src/types.ts): `src/types.ts`

### Analysis services

- [Analysis API](https://github.com/krupashetty004/ai-trading-simulator/blob/main/server.ts): `server.ts`
- [Worker runtime](https://github.com/krupashetty004/ai-trading-simulator/blob/main/worker.ts): `worker.ts`

### Other components

- **Retail trader**
- **Yahoo Finance**
- **Google Gemini**
- **Browser local storage**

## Connections

- Retail trader → Workspace navigation: uses (evidence: `README.md`)
- React entry → Workspace navigation: renders (evidence: `src/main.tsx`)
- Workspace navigation → Dashboard: routes to (evidence: `src/App.tsx`)
- Workspace navigation → Trade simulator: routes to (evidence: `src/App.tsx`)
- Workspace navigation → Portfolio review: routes to (evidence: `src/App.tsx`)
- Workspace navigation → Research brief: routes to (evidence: `src/App.tsx`)
- Workspace navigation → Methodology: routes to (evidence: `src/App.tsx`)
- Workspace navigation → Theme state: provides (evidence: `src/App.tsx`)
- Trade simulator → Historical chart: renders (evidence: `src/pages/Trading.tsx`)
- Trade simulator → Behavioral risk guard: evaluates (evidence: `src/pages/Trading.tsx`)
- Trade simulator → Analysis API: requests analysis (evidence: `src/pages/Trading.tsx`)
- Research brief → Analysis API: requests analysis (evidence: `src/pages/AIAnalysis.tsx`)
- Trade simulator → Simulation ledger: reads portfolio (evidence: `src/pages/Trading.tsx`)
- Trade simulator → Simulation ledger: records simulation (evidence: `README.md`)
- Dashboard → Simulation ledger: reads portfolio (evidence: `src/pages/Dashboard.tsx`)
- Portfolio review → Simulation ledger: reads ledger (evidence: `src/pages/Portfolio.tsx`)
- Simulation ledger → Browser local storage: persists to (evidence: `src/context/PortfolioContext.tsx`)
- Simulation ledger → Decision data types: uses types (evidence: `src/context/PortfolioContext.tsx`)
- Analysis API → Yahoo Finance: fetches history and news (evidence: `README.md`)
- Analysis API → Google Gemini: requests reasoning (evidence: `README.md`)