# manoj2883/vireo architecture

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

- Interactive diagram: https://gitdiagram.com/manoj2883/vireo
- Repository: https://github.com/manoj2883/vireo

## Overview

Vireo is a browser-based speaking-practice coach. The user chooses a situation, warms up, speaks while live transcription and on-device speech/camera analysis provide cues, then reviews field notes, retakes, and compares progress. The browser stores sessions and stories locally; the server issues transcription tokens and generates evidence-checked notes and tightened answers. README documents the overall flow; some internal links are supported only by imports or references in the source index, so unsampled details are not expanded.

Main entry points: [`src/live/LiveSessionEngine.ts`](https://github.com/manoj2883/vireo/blob/main/src/live/LiveSessionEngine.ts) (Session engine), [`server/app.js`](https://github.com/manoj2883/vireo/blob/main/server/app.js) (HTTP API), [`src/pages/FieldNotesPage.tsx`](https://github.com/manoj2883/vireo/blob/main/src/pages/FieldNotesPage.tsx) (Field notes screen), [`src/pages/WarmUpPage.tsx`](https://github.com/manoj2883/vireo/blob/main/src/pages/WarmUpPage.tsx) (Situation warm-up)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice["Practice experience"]
  node_routes["App routes<br/>[routes.tsx]"]
  node_warmup["Situation warm-up<br/>[WarmUpPage.tsx]"]
  node_situations["Practice situations<br/>[situations.ts]"]
  node_livepage["Live session screen<br/>[LivePage.tsx]"]
end

subgraph group_analysis["Live analysis"]
  node_engine["Session engine"]
  node_metrics["Speech metrics"]
  node_pitch["Pitch tracking<br/>[PitchTracker.ts]"]
  node_vision["Camera analysis<br/>[cameraTracker.ts]"]
  node_sonogram["Sonogram display<br/>[Sonogram.tsx]"]
  node_deepgram["Deepgram transcription"]
end

subgraph group_review["Review and history"]
  node_db[("Local session store<br/>[localDb.ts]")]
  node_stories["Story Bank<br/>[StoriesPage.tsx]"]
  node_notespage["Field notes screen<br/>[FieldNotesPage.tsx]"]
  node_notesapi["Field notes client<br/>[fieldNotesApi.ts]"]
  node_tightenapi["Tighten client<br/>[tightenApi.ts]"]
  node_comparison["Retake comparison<br/>[BeforeAfter.tsx]"]
  node_reports["Share and reports<br/>[TakeItWithYou.tsx]"]
end

subgraph group_backend["Server services"]
  node_api["HTTP API<br/>[app.js]"]
  node_stt["Token grants<br/>[stt.js]"]
  node_llm["Notes generation<br/>[index.js]"]
  node_evidence["Evidence checking<br/>[evidence.js]"]
  node_providers["LLM providers"]
end

node_speaker(("Speaker"))
node_mic(("Microphone"))
node_camera(("Camera"))
node_redis[("Upstash Redis")]

node_speaker -->|"uses"| node_routes
node_routes -->|"routes to"| node_warmup
node_warmup -->|"offers"| node_situations
node_warmup -->|"starts practice"| node_livepage
node_mic -->|"captures speech"| node_engine
node_camera -->|"provides frames"| node_vision
node_livepage -->|"runs"| node_engine
node_engine -->|"computes"| node_metrics
node_engine -->|"uses"| node_pitch
node_engine -->|"starts analysis"| node_vision
node_engine -->|"transcribes via"| node_deepgram
node_deepgram -->|"requests token"| node_api
node_engine -->|"feeds live display"| node_sonogram
node_engine -->|"stores sessions"| node_db
node_warmup -->|"loads practice data"| node_db
node_routes -->|"routes to"| node_notespage
node_notespage -->|"requests notes"| node_notesapi
node_notespage -->|"requests rewrite"| node_tightenapi
node_notespage -->|"updates session"| node_db
node_notespage -->|"shows retakes"| node_comparison
node_notespage -->|"offers export"| node_reports
node_stories -->|"reads stories"| node_db
node_notesapi -->|"posts transcript"| node_api
node_tightenapi -->|"posts transcript"| node_api
node_api -->|"grants token"| node_stt
node_api -->|"requests generation"| node_llm
node_llm -->|"dispatches to"| node_providers
node_api -->|"verifies notes"| node_evidence
node_api -.->|"limits usage"| node_redis

click node_routes "https://github.com/manoj2883/vireo/blob/main/src/routes.tsx"
click node_warmup "https://github.com/manoj2883/vireo/blob/main/src/pages/WarmUpPage.tsx"
click node_situations "https://github.com/manoj2883/vireo/blob/main/src/session/situations.ts"
click node_livepage "https://github.com/manoj2883/vireo/blob/main/src/pages/LivePage.tsx"
click node_engine "https://github.com/manoj2883/vireo/blob/main/src/live/LiveSessionEngine.ts"
click node_metrics "https://github.com/manoj2883/vireo/tree/main/src/live/metrics"
click node_pitch "https://github.com/manoj2883/vireo/blob/main/src/audio/pitch/PitchTracker.ts"
click node_vision "https://github.com/manoj2883/vireo/blob/main/src/vision/cameraTracker.ts"
click node_sonogram "https://github.com/manoj2883/vireo/blob/main/src/components/sonogram/Sonogram.tsx"
click node_deepgram "https://github.com/manoj2883/vireo/blob/main/src/live/deepgramLiveClient.ts"
click node_db "https://github.com/manoj2883/vireo/blob/main/src/storage/localDb.ts"
click node_stories "https://github.com/manoj2883/vireo/blob/main/src/pages/StoriesPage.tsx"
click node_notespage "https://github.com/manoj2883/vireo/blob/main/src/pages/FieldNotesPage.tsx"
click node_notesapi "https://github.com/manoj2883/vireo/blob/main/src/session/fieldNotesApi.ts"
click node_tightenapi "https://github.com/manoj2883/vireo/blob/main/src/session/tightenApi.ts"
click node_comparison "https://github.com/manoj2883/vireo/blob/main/src/components/notes/BeforeAfter.tsx"
click node_reports "https://github.com/manoj2883/vireo/blob/main/src/components/notes/TakeItWithYou.tsx"
click node_api "https://github.com/manoj2883/vireo/blob/main/server/app.js"
click node_stt "https://github.com/manoj2883/vireo/blob/main/server/stt.js"
click node_llm "https://github.com/manoj2883/vireo/blob/main/server/llm/index.js"
click node_evidence "https://github.com/manoj2883/vireo/blob/main/server/llm/evidence.js"
click node_providers "https://github.com/manoj2883/vireo/tree/main/server/llm/providers"

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_routes,node_warmup,node_situations,node_livepage toneBlue
class node_engine,node_metrics,node_pitch,node_vision,node_sonogram,node_deepgram,node_redis toneAmber
class node_db,node_stories,node_notespage,node_notesapi,node_tightenapi,node_comparison,node_reports toneMint
class node_api,node_stt,node_llm,node_evidence,node_providers toneRose
class node_speaker,node_mic,node_camera toneIndigo
```

## Components

### Practice experience

- [App routes](https://github.com/manoj2883/vireo/blob/main/src/routes.tsx): `src/routes.tsx`
- [Situation warm-up](https://github.com/manoj2883/vireo/blob/main/src/pages/WarmUpPage.tsx): `src/pages/WarmUpPage.tsx`
- [Practice situations](https://github.com/manoj2883/vireo/blob/main/src/session/situations.ts): `src/session/situations.ts`
- [Live session screen](https://github.com/manoj2883/vireo/blob/main/src/pages/LivePage.tsx): `src/pages/LivePage.tsx`

### Live analysis

- [Session engine](https://github.com/manoj2883/vireo/blob/main/src/live/LiveSessionEngine.ts): `src/live/LiveSessionEngine.ts`
- [Speech metrics](https://github.com/manoj2883/vireo/tree/main/src/live/metrics): `src/live/metrics`
- [Pitch tracking](https://github.com/manoj2883/vireo/blob/main/src/audio/pitch/PitchTracker.ts): `src/audio/pitch/PitchTracker.ts`
- [Camera analysis](https://github.com/manoj2883/vireo/blob/main/src/vision/cameraTracker.ts): `src/vision/cameraTracker.ts`
- [Sonogram display](https://github.com/manoj2883/vireo/blob/main/src/components/sonogram/Sonogram.tsx): `src/components/sonogram/Sonogram.tsx`
- [Deepgram transcription](https://github.com/manoj2883/vireo/blob/main/src/live/deepgramLiveClient.ts): `src/live/deepgramLiveClient.ts`

### Review and history

- [Local session store](https://github.com/manoj2883/vireo/blob/main/src/storage/localDb.ts): `src/storage/localDb.ts`
- [Story Bank](https://github.com/manoj2883/vireo/blob/main/src/pages/StoriesPage.tsx): `src/pages/StoriesPage.tsx`
- [Field notes screen](https://github.com/manoj2883/vireo/blob/main/src/pages/FieldNotesPage.tsx): `src/pages/FieldNotesPage.tsx`
- [Field notes client](https://github.com/manoj2883/vireo/blob/main/src/session/fieldNotesApi.ts): `src/session/fieldNotesApi.ts`
- [Tighten client](https://github.com/manoj2883/vireo/blob/main/src/session/tightenApi.ts): `src/session/tightenApi.ts`
- [Retake comparison](https://github.com/manoj2883/vireo/blob/main/src/components/notes/BeforeAfter.tsx): `src/components/notes/BeforeAfter.tsx`
- [Share and reports](https://github.com/manoj2883/vireo/blob/main/src/components/notes/TakeItWithYou.tsx): `src/components/notes/TakeItWithYou.tsx`

### Server services

- [HTTP API](https://github.com/manoj2883/vireo/blob/main/server/app.js): `server/app.js`
- [Token grants](https://github.com/manoj2883/vireo/blob/main/server/stt.js): `server/stt.js`
- [Notes generation](https://github.com/manoj2883/vireo/blob/main/server/llm/index.js): `server/llm/index.js`
- [Evidence checking](https://github.com/manoj2883/vireo/blob/main/server/llm/evidence.js): `server/llm/evidence.js`
- [LLM providers](https://github.com/manoj2883/vireo/tree/main/server/llm/providers): `server/llm/providers`

### Other components

- **Speaker**
- **Microphone**
- **Camera**
- **Upstash Redis**

## Connections

- Speaker → App routes: uses
- App routes → Situation warm-up: routes to (evidence: `src/routes.tsx`)
- Situation warm-up → Practice situations: offers (evidence: `src/session/situations.ts`)
- Situation warm-up → Live session screen: starts practice
- Microphone → Session engine: captures speech
- Camera → Camera analysis: provides frames
- Live session screen → Session engine: runs (evidence: `src/live/LiveSessionEngine.ts`)
- Session engine → Speech metrics: computes (evidence: `src/live/LiveSessionEngine.ts`)
- Session engine → Pitch tracking: uses (evidence: `src/live/LiveSessionEngine.ts`)
- Session engine → Camera analysis: starts analysis (evidence: `src/live/LiveSessionEngine.ts`)
- Session engine → Deepgram transcription: transcribes via (evidence: `src/live/LiveSessionEngine.ts`)
- Deepgram transcription → HTTP API: requests token
- Session engine → Sonogram display: feeds live display
- Session engine → Local session store: stores sessions (evidence: `src/storage/localDb.ts`)
- Situation warm-up → Local session store: loads practice data (evidence: `src/pages/WarmUpPage.tsx`)
- App routes → Field notes screen: routes to (evidence: `src/routes.tsx`)
- Field notes screen → Field notes client: requests notes (evidence: `src/pages/FieldNotesPage.tsx`)
- Field notes screen → Tighten client: requests rewrite (evidence: `src/pages/FieldNotesPage.tsx`)
- Field notes screen → Local session store: updates session (evidence: `src/pages/FieldNotesPage.tsx`)
- Field notes screen → Retake comparison: shows retakes (evidence: `src/pages/FieldNotesPage.tsx`)
- Field notes screen → Share and reports: offers export (evidence: `src/pages/FieldNotesPage.tsx`)
- Story Bank → Local session store: reads stories
- Field notes client → HTTP API: posts transcript
- Tighten client → HTTP API: posts transcript (evidence: `server/app.js`)
- HTTP API → Token grants: grants token (evidence: `server/app.js`)
- HTTP API → Notes generation: requests generation (evidence: `server/app.js`)
- Notes generation → LLM providers: dispatches to (evidence: `server/llm/index.js`)
- HTTP API → Evidence checking: verifies notes (evidence: `server/app.js`)
- HTTP API → Upstash Redis: limits usage