# riteeessshhh/speak-forge architecture

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

- Interactive diagram: https://gitdiagram.com/riteeessshhh/speak-forge
- Repository: https://github.com/riteeessshhh/speak-forge

## Overview

Speak Forge is an impromptu-speaking practice and coaching application. A user signs in, chooses a speaking track and difficulty, receives a prompt, records a timed response, reviews the recording and AI feedback, and can track progress in analytics. The frontend owns the practice experience; backend routes handle identity, prompt generation, recording analysis, and analytics persistence. README documents the split external-AI/storage and SQL upload stages; sampled route excerpts substantiate topic generation, authentication, and persistence. Some client-to-API wiring is not shown in the excerpts, so those links are omitted or marked unverified.

Main entry points: [`client/src/App.jsx`](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/App.jsx) (Practice App), [`server/routes/topics.js`](https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/topics.js) (Topic Generation), [`server/routes/upload.js`](https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/upload.js) (Recording Analysis), [`server/index.js`](https://github.com/riteeessshhh/speak-forge/blob/main/server/index.js) (Express API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice["Practice Experience"]
  node_app["Practice App<br/>[App.jsx]"]
  node_topics["Local Topic Bank<br/>[topics.js]"]
  node_difficulty["Difficulty Selector"]
  node_timer["Countdown Timer<br/>[CountdownTimer.jsx]"]
  node_recorder["Audio Recorder"]
  node_visualizer["Audio Visualizer"]
  node_player["Audio Player<br/>[AudioPlayer.jsx]"]
  node_dashboard["Analytics Dashboard<br/>[Dashboard.jsx]"]
end

subgraph group_identity["Identity"]
  node_authview["Authentication View<br/>[AuthView.jsx]"]
  node_usercontext["User Context<br/>[UserContext.jsx]"]
  node_authroute["Auth Routes<br/>[auth.js]"]
  node_authmiddleware["JWT Middleware<br/>[auth.js]"]
end

subgraph group_backend["Backend Services"]
  node_api["Express API<br/>[index.js]"]
  node_topicroute["Topic Generation<br/>[topics.js]"]
  node_uploadroute["Recording Analysis<br/>[upload.js]"]
  node_analyticsroute["Analytics Routes<br/>[analytics.js]"]
  node_validation["Request Validation<br/>[validate.js]"]
end

subgraph group_data["Persistence and Intelligence"]
  node_queries["SQL Queries<br/>[queries.js]"]
  node_pool[("PostgreSQL Pool<br/>[pool.js]")]
  node_ai["Gemini Orchestration<br/>[ai.js]"]
  node_supabase["Supabase Storage<br/>[supabase.js]"]
end

node_speaker(("Speaker"))
node_groq["Groq Whisper"]
node_gemini["Gemini Service"]
node_postgres[("PostgreSQL")]

node_speaker -->|"practices with"| node_app
node_app -->|"shows when signed out"| node_authview
node_authview -->|"uses"| node_usercontext
node_app -->|"selects prompts from"| node_topics
node_app -->|"offers selection"| node_difficulty
node_app -->|"renders"| node_timer
node_app -->|"uses recording state machine"| node_recorder
node_app -->|"renders"| node_visualizer
node_app -->|"renders review"| node_player
node_app -->|"shows progress"| node_dashboard
node_app -.->|"submits practice data"| node_api
node_api -->|"mounts"| node_authroute
node_api -->|"mounts"| node_topicroute
node_api -->|"mounts"| node_uploadroute
node_api -->|"mounts"| node_analyticsroute
node_authroute -->|"validates signup and login"| node_validation
node_topicroute -->|"validates topic request"| node_validation
node_authroute -->|"uses cookie options"| node_authmiddleware
node_topicroute -->|"requires token"| node_authmiddleware
node_uploadroute -->|"requires token"| node_authmiddleware
node_authroute -->|"reads and creates users"| node_queries
node_topicroute -->|"selects and marks topics"| node_queries
node_analyticsroute -->|"reads session metrics"| node_queries
node_uploadroute -->|"persists session and scores"| node_queries
node_queries -->|"imports pool"| node_pool
node_authroute -->|"acquires clients"| node_pool
node_topicroute -->|"acquires clients"| node_pool
node_uploadroute -->|"requests analysis"| node_ai
node_topicroute -->|"generates fallback topics"| node_ai
node_ai -->|"generates content"| node_gemini
node_uploadroute -->|"transcribes audio"| node_groq
node_uploadroute -->|"uploads recordings"| node_supabase
node_pool -->|"connects"| node_postgres
node_queries -->|"queries and writes"| node_postgres
node_dashboard -.->|"loads analytics"| node_api

click node_app "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/App.jsx"
click node_topics "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/data/topics.js"
click node_difficulty "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/DifficultySelector.jsx"
click node_timer "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/CountdownTimer.jsx"
click node_recorder "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/hooks/useAudioRecorder.js"
click node_visualizer "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/AudioVisualizer.jsx"
click node_player "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/AudioPlayer.jsx"
click node_dashboard "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/Dashboard.jsx"
click node_authview "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/AuthView.jsx"
click node_usercontext "https://github.com/riteeessshhh/speak-forge/blob/main/client/src/contexts/UserContext.jsx"
click node_authroute "https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/auth.js"
click node_authmiddleware "https://github.com/riteeessshhh/speak-forge/blob/main/server/middleware/auth.js"
click node_api "https://github.com/riteeessshhh/speak-forge/blob/main/server/index.js"
click node_topicroute "https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/topics.js"
click node_uploadroute "https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/upload.js"
click node_analyticsroute "https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/analytics.js"
click node_validation "https://github.com/riteeessshhh/speak-forge/blob/main/server/middleware/validate.js"
click node_queries "https://github.com/riteeessshhh/speak-forge/blob/main/server/db/queries.js"
click node_pool "https://github.com/riteeessshhh/speak-forge/blob/main/server/db/pool.js"
click node_ai "https://github.com/riteeessshhh/speak-forge/blob/main/server/lib/ai.js"
click node_supabase "https://github.com/riteeessshhh/speak-forge/blob/main/server/lib/supabase.js"

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_app,node_topics,node_difficulty,node_timer,node_recorder,node_visualizer,node_player,node_dashboard toneBlue
class node_authview,node_usercontext,node_authroute,node_authmiddleware,node_postgres toneAmber
class node_api,node_topicroute,node_uploadroute,node_analyticsroute,node_validation toneMint
class node_queries,node_pool,node_ai,node_supabase toneRose
class node_speaker,node_groq,node_gemini toneIndigo
```

## Components

### Practice Experience

- [Practice App](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Local Topic Bank](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/data/topics.js): `client/src/data/topics.js`
- [Difficulty Selector](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/DifficultySelector.jsx): `client/src/components/DifficultySelector.jsx`
- [Countdown Timer](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/CountdownTimer.jsx): `client/src/components/CountdownTimer.jsx`
- [Audio Recorder](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/hooks/useAudioRecorder.js): `client/src/hooks/useAudioRecorder.js`
- [Audio Visualizer](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/AudioVisualizer.jsx): `client/src/components/AudioVisualizer.jsx`
- [Audio Player](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/AudioPlayer.jsx): `client/src/components/AudioPlayer.jsx`
- [Analytics Dashboard](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/Dashboard.jsx): `client/src/components/Dashboard.jsx`

### Identity

- [Authentication View](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/components/AuthView.jsx): `client/src/components/AuthView.jsx`
- [User Context](https://github.com/riteeessshhh/speak-forge/blob/main/client/src/contexts/UserContext.jsx): `client/src/contexts/UserContext.jsx`
- [Auth Routes](https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/auth.js): `server/routes/auth.js`
- [JWT Middleware](https://github.com/riteeessshhh/speak-forge/blob/main/server/middleware/auth.js): `server/middleware/auth.js`

### Backend Services

- [Express API](https://github.com/riteeessshhh/speak-forge/blob/main/server/index.js): `server/index.js`
- [Topic Generation](https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/topics.js): `server/routes/topics.js`
- [Recording Analysis](https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/upload.js): `server/routes/upload.js`
- [Analytics Routes](https://github.com/riteeessshhh/speak-forge/blob/main/server/routes/analytics.js): `server/routes/analytics.js`
- [Request Validation](https://github.com/riteeessshhh/speak-forge/blob/main/server/middleware/validate.js): `server/middleware/validate.js`

### Persistence and Intelligence

- [SQL Queries](https://github.com/riteeessshhh/speak-forge/blob/main/server/db/queries.js): `server/db/queries.js`
- [PostgreSQL Pool](https://github.com/riteeessshhh/speak-forge/blob/main/server/db/pool.js): `server/db/pool.js`
- [Gemini Orchestration](https://github.com/riteeessshhh/speak-forge/blob/main/server/lib/ai.js): `server/lib/ai.js`
- [Supabase Storage](https://github.com/riteeessshhh/speak-forge/blob/main/server/lib/supabase.js): `server/lib/supabase.js`

### Other components

- **Speaker**
- **Groq Whisper**
- **Gemini Service**
- **PostgreSQL**

## Connections

- Speaker → Practice App: practices with (evidence: `README.md`)
- Practice App → Authentication View: shows when signed out (evidence: `client/src/App.jsx`)
- Authentication View → User Context: uses (evidence: `client/src/components/AuthView.jsx`)
- Practice App → Local Topic Bank: selects prompts from (evidence: `client/src/App.jsx`)
- Practice App → Difficulty Selector: offers selection
- Practice App → Countdown Timer: renders (evidence: `client/src/App.jsx`)
- Practice App → Audio Recorder: uses recording state machine (evidence: `client/src/App.jsx`)
- Practice App → Audio Visualizer: renders (evidence: `client/src/App.jsx`)
- Practice App → Audio Player: renders review (evidence: `client/src/App.jsx`)
- Practice App → Analytics Dashboard: shows progress (evidence: `client/src/App.jsx`)
- Practice App → Express API: submits practice data
- Express API → Auth Routes: mounts (evidence: `server/index.js`)
- Express API → Topic Generation: mounts (evidence: `server/index.js`)
- Express API → Recording Analysis: mounts (evidence: `server/index.js`)
- Express API → Analytics Routes: mounts (evidence: `server/index.js`)
- Auth Routes → Request Validation: validates signup and login (evidence: `server/routes/auth.js`)
- Topic Generation → Request Validation: validates topic request (evidence: `server/routes/topics.js`)
- Auth Routes → JWT Middleware: uses cookie options (evidence: `server/routes/auth.js`)
- Topic Generation → JWT Middleware: requires token (evidence: `server/routes/topics.js`)
- Recording Analysis → JWT Middleware: requires token (evidence: `server/routes/upload.js`)
- Auth Routes → SQL Queries: reads and creates users (evidence: `server/routes/auth.js`)
- Topic Generation → SQL Queries: selects and marks topics (evidence: `server/routes/topics.js`)
- Analytics Routes → SQL Queries: reads session metrics (evidence: `server/routes/analytics.js`)
- Recording Analysis → SQL Queries: persists session and scores (evidence: `server/routes/upload.js`)
- SQL Queries → PostgreSQL Pool: imports pool (evidence: `server/db/queries.js`)
- Auth Routes → PostgreSQL Pool: acquires clients (evidence: `server/routes/auth.js`)
- Topic Generation → PostgreSQL Pool: acquires clients (evidence: `server/routes/topics.js`)
- Recording Analysis → Gemini Orchestration: requests analysis (evidence: `server/routes/upload.js`)
- Topic Generation → Gemini Orchestration: generates fallback topics (evidence: `server/routes/topics.js`)
- Gemini Orchestration → Gemini Service: generates content (evidence: `server/lib/ai.js`)
- Recording Analysis → Groq Whisper: transcribes audio (evidence: `README.md`)
- Recording Analysis → Supabase Storage: uploads recordings (evidence: `server/routes/upload.js`)
- PostgreSQL Pool → PostgreSQL: connects (evidence: `server/db/pool.js`)
- SQL Queries → PostgreSQL: queries and writes (evidence: `server/db/queries.js`)
- Analytics Dashboard → Express API: loads analytics
