# naavalanarul/lecture_whisper architecture

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

- Interactive diagram: https://gitdiagram.com/naavalanarul/lecture_whisper
- Repository: https://github.com/naavalanarul/lecture_whisper

## Overview

Lecture Whisper is a local-first lecture capture and academic-intelligence system: recordings are captured or uploaded, processed into transcripts and study materials, persisted locally, and reviewed in the web dashboard; an Android companion pairs and syncs with the server. The README also documents timetable OCR, speaker/event/question intelligence, and correction workflows. Some server and UI subsystems are represented by their exact enclosing paths because their implementation was not sampled; edges are limited to documented or sampled interactions.

Main entry points: [`server/src/lecturewhisper/pipeline/runner.py`](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/runner.py) (Pipeline runner), [`ui/src/api.ts`](https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/api.ts) (Dashboard API client), [`server/src/lecturewhisper/api/jobs.py`](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/jobs.py) (Job queue), [`mobile/android/app/src/main/java/com/lecturewhisper/MainActivity.java`](https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/MainActivity.java) (Android app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture & Pairing"]
  node_android["Android app<br/>[MainActivity.java]"]
  node_recorder["Audio recorder"]
  node_connection["Connection manager"]
  node_sync["Laptop sync client"]
end

subgraph group_server["Local Server"]
  node_api["FastAPI application<br/>[app.py]"]
  node_upload["Audio upload<br/>[upload.py]"]
  node_pairing["Pairing API<br/>[pairing.py]"]
  node_jobs["Job queue<br/>[jobs.py]"]
  node_jobroutes["Job status &amp; events<br/>[job_routes.py]"]
  node_recordings["Recording API<br/>[recordings.py]"]
  node_timetable["Timetable API<br/>[timetable.py]"]
  node_database[("SQLite database<br/>[database.py]")]
  node_files["Audio &amp; artifacts<br/>[files.py]"]
end

subgraph group_processing["Lecture Processing"]
  node_runner["Pipeline runner<br/>[runner.py]"]
  node_audio["Audio preparation<br/>[audio.py]"]
  node_asr["Speech recognition<br/>[asr.py]"]
  node_diarize["Speaker diarization<br/>[diarize.py]"]
  node_notes["Study notes<br/>[notes.py]"]
  node_chapters["Chapters &amp; events<br/>[chapters.py]"]
  node_timetablepipe["Schedule extraction<br/>[timetable.py]"]
  node_llm["Structured LLM<br/>[engine.py]"]
end

subgraph group_review["Review &amp; Study"]
  node_dashboard["Web dashboard<br/>[App.tsx]"]
  node_lectureview["Lecture study view<br/>[LectureView.tsx]"]
  node_corrections["Corrections"]
  node_webapi["Dashboard API client<br/>[api.ts]"]
end

node_student(("Student"))
node_mlx{{"Local ML runtime"}}

node_student -->|"records / pairs"| node_android
node_android -->|"starts recording"| node_recorder
node_android -->|"discovers host"| node_connection
node_android -->|"syncs audio"| node_sync
node_sync -->|"uploads chunks"| node_upload
node_student -->|"uploads / reviews"| node_dashboard
node_dashboard -->|"requests data"| node_webapi
node_webapi -->|"submits audio"| node_upload
node_webapi -->|"loads recordings"| node_recordings
node_webapi -->|"loads schedule"| node_timetable
node_webapi -->|"gets pairing info"| node_pairing
node_api -->|"registers routes"| node_upload
node_api -->|"registers routes"| node_pairing
node_api -->|"starts worker"| node_jobs
node_upload -->|"queues processing"| node_jobs
node_webapi -->|"queues processing"| node_jobs
node_jobroutes -->|"reads status / streams"| node_jobs
node_jobs -->|"dispatches work"| node_runner
node_runner -->|"prepares audio"| node_audio
node_runner -->|"transcribes"| node_asr
node_runner -->|"identifies speakers"| node_diarize
node_runner -->|"generates notes"| node_notes
node_runner -->|"extracts chapters"| node_chapters
node_runner -->|"extracts schedule"| node_timetablepipe
node_notes -->|"requests generation"| node_llm
node_chapters -->|"requests extraction"| node_llm
node_timetablepipe -->|"requests OCR"| node_llm
node_llm -.->|"runs inference"| node_mlx
node_recordings -->|"reads / writes metadata"| node_database
node_timetable -->|"reads / writes schedule"| node_database
node_runner -->|"stores artifacts"| node_files
node_dashboard -->|"shows selected lecture"| node_lectureview
node_dashboard -->|"opens review tools"| node_corrections
node_corrections -->|"submits corrections"| node_webapi
node_lectureview -->|"loads lecture data"| node_webapi

click node_android "https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/MainActivity.java"
click node_recorder "https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/recorder/RecorderService.java"
click node_connection "https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/network/ConnectionManager.java"
click node_sync "https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/network/LaptopSyncClient.java"
click node_api "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/app.py"
click node_upload "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/upload.py"
click node_pairing "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/pairing.py"
click node_jobs "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/jobs.py"
click node_jobroutes "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/job_routes.py"
click node_recordings "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/recordings.py"
click node_timetable "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/timetable.py"
click node_database "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/store/database.py"
click node_files "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/store/files.py"
click node_runner "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/runner.py"
click node_audio "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/audio.py"
click node_asr "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/asr.py"
click node_diarize "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/diarize.py"
click node_notes "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/notes.py"
click node_chapters "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/chapters.py"
click node_timetablepipe "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/timetable.py"
click node_llm "https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/llm/engine.py"
click node_dashboard "https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/App.tsx"
click node_lectureview "https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/views/LectureView.tsx"
click node_corrections "https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/views/CorrectionsView.tsx"
click node_webapi "https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/api.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_android,node_recorder,node_connection,node_sync toneBlue
class node_api,node_upload,node_pairing,node_jobs,node_jobroutes,node_recordings,node_timetable,node_database,node_files toneAmber
class node_runner,node_audio,node_asr,node_diarize,node_notes,node_chapters,node_timetablepipe,node_llm toneMint
class node_dashboard,node_lectureview,node_corrections,node_webapi toneRose
class node_student,node_mlx toneIndigo
```

## Components

### Capture & Pairing

- [Android app](https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/MainActivity.java): `mobile/android/app/src/main/java/com/lecturewhisper/MainActivity.java`
- [Audio recorder](https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/recorder/RecorderService.java): `mobile/android/app/src/main/java/com/lecturewhisper/recorder/RecorderService.java`
- [Connection manager](https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/network/ConnectionManager.java): `mobile/android/app/src/main/java/com/lecturewhisper/network/ConnectionManager.java`
- [Laptop sync client](https://github.com/naavalanarul/lecture_whisper/blob/main/mobile/android/app/src/main/java/com/lecturewhisper/network/LaptopSyncClient.java): `mobile/android/app/src/main/java/com/lecturewhisper/network/LaptopSyncClient.java`

### Local Server

- [FastAPI application](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/app.py): `server/src/lecturewhisper/api/app.py`
- [Audio upload](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/upload.py): `server/src/lecturewhisper/api/routes/upload.py`
- [Pairing API](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/pairing.py): `server/src/lecturewhisper/api/routes/pairing.py`
- [Job queue](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/jobs.py): `server/src/lecturewhisper/api/jobs.py`
- [Job status & events](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/job_routes.py): `server/src/lecturewhisper/api/routes/job_routes.py`
- [Recording API](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/recordings.py): `server/src/lecturewhisper/api/routes/recordings.py`
- [Timetable API](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/api/routes/timetable.py): `server/src/lecturewhisper/api/routes/timetable.py`
- [SQLite database](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/store/database.py): `server/src/lecturewhisper/store/database.py`
- [Audio & artifacts](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/store/files.py): `server/src/lecturewhisper/store/files.py`

### Lecture Processing

- [Pipeline runner](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/runner.py): `server/src/lecturewhisper/pipeline/runner.py`
- [Audio preparation](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/audio.py): `server/src/lecturewhisper/pipeline/audio.py`
- [Speech recognition](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/asr.py): `server/src/lecturewhisper/pipeline/asr.py`
- [Speaker diarization](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/diarize.py): `server/src/lecturewhisper/pipeline/diarize.py`
- [Study notes](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/notes.py): `server/src/lecturewhisper/pipeline/notes.py`
- [Chapters & events](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/chapters.py): `server/src/lecturewhisper/pipeline/chapters.py`
- [Schedule extraction](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/pipeline/timetable.py): `server/src/lecturewhisper/pipeline/timetable.py`
- [Structured LLM](https://github.com/naavalanarul/lecture_whisper/blob/main/server/src/lecturewhisper/llm/engine.py): `server/src/lecturewhisper/llm/engine.py`

### Review & Study

- [Web dashboard](https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [Lecture study view](https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/views/LectureView.tsx): `ui/src/views/LectureView.tsx`
- [Corrections](https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/views/CorrectionsView.tsx): `ui/src/views/CorrectionsView.tsx`
- [Dashboard API client](https://github.com/naavalanarul/lecture_whisper/blob/main/ui/src/api.ts): `ui/src/api.ts`

### Other components

- **Student**
- **Local ML runtime**

## Connections

- Student → Android app: records / pairs
- Android app → Audio recorder: starts recording
- Android app → Connection manager: discovers host
- Android app → Laptop sync client: syncs audio
- Laptop sync client → Audio upload: uploads chunks
- Student → Web dashboard: uploads / reviews
- Web dashboard → Dashboard API client: requests data
- Dashboard API client → Audio upload: submits audio
- Dashboard API client → Recording API: loads recordings
- Dashboard API client → Timetable API: loads schedule
- Dashboard API client → Pairing API: gets pairing info
- FastAPI application → Audio upload: registers routes
- FastAPI application → Pairing API: registers routes
- FastAPI application → Job queue: starts worker
- Audio upload → Job queue: queues processing
- Dashboard API client → Job queue: queues processing
- Job status & events → Job queue: reads status / streams
- Job queue → Pipeline runner: dispatches work
- Pipeline runner → Audio preparation: prepares audio
- Pipeline runner → Speech recognition: transcribes
- Pipeline runner → Speaker diarization: identifies speakers
- Pipeline runner → Study notes: generates notes
- Pipeline runner → Chapters & events: extracts chapters
- Pipeline runner → Schedule extraction: extracts schedule
- Study notes → Structured LLM: requests generation
- Chapters & events → Structured LLM: requests extraction
- Schedule extraction → Structured LLM: requests OCR
- Structured LLM → Local ML runtime: runs inference
- Recording API → SQLite database: reads / writes metadata
- Timetable API → SQLite database: reads / writes schedule
- Pipeline runner → Audio & artifacts: stores artifacts
- Web dashboard → Lecture study view: shows selected lecture
- Web dashboard → Corrections: opens review tools
- Corrections → Dashboard API client: submits corrections
- Lecture study view → Dashboard API client: loads lecture data