# rammelz-v2/vocalink-web architecture

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

- Interactive diagram: https://gitdiagram.com/rammelz-v2/vocalink-web
- Repository: https://github.com/rammelz-v2/vocalink-web

## Overview

VocaLink’s web application is the teacher-facing console for classroom sessions: teachers sign in, review student activity, manage students, broadcast speech or text, and inspect live-caption/session logs. The React app routes these workflows through page components and polling hooks to a FastAPI service; authentication is handled separately through the auth context. The README also documents a student mobile app and backend capabilities such as AAC prediction and Whisper transcription, but their implementations are outside this repository. Edges reflect the excerpts, source-index references, or documented relationships; unsampled features are not expanded into unsupported code paths.

Main entry points: [`src/App.tsx`](https://github.com/rammelz-v2/vocalink-web/blob/main/src/App.tsx) (App routing), [`src/services/api.ts`](https://github.com/rammelz-v2/vocalink-web/blob/main/src/services/api.ts) (API client), [`src/pages/Broadcast.tsx`](https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Broadcast.tsx) (Broadcast page), [`src/context/AuthContext.tsx`](https://github.com/rammelz-v2/vocalink-web/blob/main/src/context/AuthContext.tsx) (Auth context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Teacher web app"]
  node_app["App routing<br/>[App.tsx]"]
  node_settings["Teacher settings<br/>[Settings.tsx]"]
end

subgraph group_identity["Identity"]
  node_authpages["Auth pages"]
  node_authcontext["Auth context<br/>[AuthContext.tsx]"]
  node_authservice["Auth service<br/>[authService.ts]"]
end

subgraph group_classroom["Classroom workflows"]
  node_dashboard["Dashboard<br/>[Dashboard.tsx]"]
  node_dashboarddata["Dashboard data"]
  node_students["Student management<br/>[Students.tsx]"]
  node_broadcast["Broadcast page<br/>[Broadcast.tsx]"]
  node_sessionhook["Broadcast session"]
  node_controls["Broadcast controls<br/>[ControlBar.tsx]"]
  node_requests["Student requests<br/>[RequestsPanel.tsx]"]
  node_livecc["Live CC page<br/>[LiveCC.tsx]"]
  node_livehook["Session log polling"]
  node_selector["Session selector"]
end

subgraph group_services["Service boundary"]
  node_api["API client<br/>[api.ts]"]
  node_backend["FastAPI backend"]
end

node_teacher(("Teacher"))
node_student["Student mobile app"]
node_speech["Browser speech recognition"]
node_database[("PostgreSQL")]

node_teacher -->|"uses console"| node_app
node_app -->|"routes to"| node_authpages
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_students
node_app -->|"routes to"| node_broadcast
node_app -->|"routes to"| node_livecc
node_app -->|"routes to"| node_settings
node_authpages -->|"authenticates via"| node_authcontext
node_authcontext -->|"sends auth requests"| node_backend
node_authcontext -.->|"provides auth state"| node_api
node_dashboard -->|"loads data via"| node_dashboarddata
node_dashboarddata -->|"requests data"| node_api
node_students -->|"requests student data"| node_api
node_broadcast -->|"uses session state"| node_sessionhook
node_broadcast -->|"renders controls"| node_controls
node_broadcast -->|"renders requests"| node_requests
node_sessionhook -->|"polls and posts"| node_api
node_sessionhook -->|"recognizes speech"| node_speech
node_livecc -->|"loads session logs"| node_livehook
node_livecc -->|"renders selector"| node_selector
node_livehook -->|"polls session logs"| node_api
node_settings -->|"loads profile"| node_api
node_api -->|"sends API requests"| node_backend
node_backend -->|"reads and writes"| node_database
node_student -->|"uses AAC and sessions"| node_backend

click node_app "https://github.com/rammelz-v2/vocalink-web/blob/main/src/App.tsx"
click node_authpages "https://github.com/rammelz-v2/vocalink-web/tree/main/src/pages/auth"
click node_authcontext "https://github.com/rammelz-v2/vocalink-web/blob/main/src/context/AuthContext.tsx"
click node_authservice "https://github.com/rammelz-v2/vocalink-web/blob/main/src/services/authService.ts"
click node_api "https://github.com/rammelz-v2/vocalink-web/blob/main/src/services/api.ts"
click node_dashboard "https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Dashboard.tsx"
click node_dashboarddata "https://github.com/rammelz-v2/vocalink-web/blob/main/src/hooks/useDashboardData.ts"
click node_students "https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Students.tsx"
click node_broadcast "https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Broadcast.tsx"
click node_sessionhook "https://github.com/rammelz-v2/vocalink-web/blob/main/src/hooks/useBroadcastSession.ts"
click node_controls "https://github.com/rammelz-v2/vocalink-web/blob/main/src/components/broadcast/ControlBar.tsx"
click node_requests "https://github.com/rammelz-v2/vocalink-web/blob/main/src/components/broadcast/RequestsPanel.tsx"
click node_livecc "https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/LiveCC.tsx"
click node_livehook "https://github.com/rammelz-v2/vocalink-web/blob/main/src/hooks/useLiveCCSessions.ts"
click node_selector "https://github.com/rammelz-v2/vocalink-web/blob/main/src/components/livecc/SessionSelector.tsx"
click node_settings "https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Settings.tsx"

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_settings,node_speech toneBlue
class node_authpages,node_authcontext,node_authservice,node_database toneAmber
class node_dashboard,node_dashboarddata,node_students,node_broadcast,node_sessionhook,node_controls,node_requests,node_livecc,node_livehook,node_selector toneMint
class node_api,node_backend toneRose
class node_teacher,node_student toneIndigo
```

## Components

### Teacher web app

- [App routing](https://github.com/rammelz-v2/vocalink-web/blob/main/src/App.tsx): `src/App.tsx`
- [Teacher settings](https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Settings.tsx): `src/pages/Settings.tsx`

### Identity

- [Auth pages](https://github.com/rammelz-v2/vocalink-web/tree/main/src/pages/auth): `src/pages/auth`
- [Auth context](https://github.com/rammelz-v2/vocalink-web/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Auth service](https://github.com/rammelz-v2/vocalink-web/blob/main/src/services/authService.ts): `src/services/authService.ts`

### Classroom workflows

- [Dashboard](https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Dashboard.tsx): `src/pages/Dashboard.tsx`
- [Dashboard data](https://github.com/rammelz-v2/vocalink-web/blob/main/src/hooks/useDashboardData.ts): `src/hooks/useDashboardData.ts`
- [Student management](https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Students.tsx): `src/pages/Students.tsx`
- [Broadcast page](https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/Broadcast.tsx): `src/pages/Broadcast.tsx`
- [Broadcast session](https://github.com/rammelz-v2/vocalink-web/blob/main/src/hooks/useBroadcastSession.ts): `src/hooks/useBroadcastSession.ts`
- [Broadcast controls](https://github.com/rammelz-v2/vocalink-web/blob/main/src/components/broadcast/ControlBar.tsx): `src/components/broadcast/ControlBar.tsx`
- [Student requests](https://github.com/rammelz-v2/vocalink-web/blob/main/src/components/broadcast/RequestsPanel.tsx): `src/components/broadcast/RequestsPanel.tsx`
- [Live CC page](https://github.com/rammelz-v2/vocalink-web/blob/main/src/pages/LiveCC.tsx): `src/pages/LiveCC.tsx`
- [Session log polling](https://github.com/rammelz-v2/vocalink-web/blob/main/src/hooks/useLiveCCSessions.ts): `src/hooks/useLiveCCSessions.ts`
- [Session selector](https://github.com/rammelz-v2/vocalink-web/blob/main/src/components/livecc/SessionSelector.tsx): `src/components/livecc/SessionSelector.tsx`

### Service boundary

- [API client](https://github.com/rammelz-v2/vocalink-web/blob/main/src/services/api.ts): `src/services/api.ts`
- **FastAPI backend**

### Other components

- **Teacher**
- **Student mobile app**
- **Browser speech recognition**
- **PostgreSQL**

## Connections

- Teacher → App routing: uses console (evidence: `README.md`)
- App routing → Auth pages: routes to (evidence: `src/App.tsx`)
- App routing → Dashboard: routes to (evidence: `src/App.tsx`)
- App routing → Student management: routes to (evidence: `src/App.tsx`)
- App routing → Broadcast page: routes to (evidence: `src/App.tsx`)
- App routing → Live CC page: routes to (evidence: `src/App.tsx`)
- App routing → Teacher settings: routes to (evidence: `src/App.tsx`)
- Auth pages → Auth context: authenticates via
- Auth context → FastAPI backend: sends auth requests (evidence: `src/context/AuthContext.tsx`)
- Auth context → API client: provides auth state
- Dashboard → Dashboard data: loads data via (evidence: `src/pages/Dashboard.tsx`)
- Dashboard data → API client: requests data (evidence: `src/hooks/useDashboardData.ts`)
- Student management → API client: requests student data (evidence: `src/pages/Students.tsx`)
- Broadcast page → Broadcast session: uses session state (evidence: `src/pages/Broadcast.tsx`)
- Broadcast page → Broadcast controls: renders controls (evidence: `src/pages/Broadcast.tsx`)
- Broadcast page → Student requests: renders requests (evidence: `src/pages/Broadcast.tsx`)
- Broadcast session → API client: polls and posts (evidence: `src/hooks/useBroadcastSession.ts`)
- Broadcast session → Browser speech recognition: recognizes speech (evidence: `README.md`)
- Live CC page → Session log polling: loads session logs (evidence: `src/pages/LiveCC.tsx`)
- Live CC page → Session selector: renders selector (evidence: `src/pages/LiveCC.tsx`)
- Session log polling → API client: polls session logs (evidence: `src/hooks/useLiveCCSessions.ts`)
- Teacher settings → API client: loads profile (evidence: `src/pages/Settings.tsx`)
- API client → FastAPI backend: sends API requests (evidence: `src/services/api.ts`)
- FastAPI backend → PostgreSQL: reads and writes (evidence: `README.md`)
- Student mobile app → FastAPI backend: uses AAC and sessions (evidence: `README.md`)
