# nthclrd/unicast-transcript architecture

> Architecture diagram of the GitHub repository nthclrd/unicast-transcript, 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/nthclrd/unicast-transcript
- Repository: https://github.com/nthclrd/unicast-transcript

## Overview

Unicast Transcriber is a local web application and CLI for selecting course podcasts, downloading audio, and optionally producing Deepgram transcripts. The main web flow runs from the browser UI through the API server, Unicast course/podcast discovery, a background download job, and transcription to local files; users can view transcripts and open the output folder. The CLI offers a parallel interactive entry point. Edges are limited to relationships shown in excerpts or documented in the README; unsampled server routes and frontend API details are represented conservatively.

Main entry points: [`server.py`](https://github.com/nthclrd/unicast-transcript/blob/main/server.py) (Local API server), [`frontend/src/App.tsx`](https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/App.tsx) (Web workflow), [`transcribe.py`](https://github.com/nthclrd/unicast-transcript/blob/main/transcribe.py) (Transcription engine), [`auth.py`](https://github.com/nthclrd/unicast-transcript/blob/main/auth.py) (Unicast login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Local interface"]
  node_web_ui["Web workflow<br/>[App.tsx]"]
  node_course_picker["Course picker<br/>[CoursePicker.tsx]"]
  node_podcast_picker["Podcast selection<br/>[PodcastPicker.tsx]"]
  node_settings["Credentials settings<br/>[SettingsDialog.tsx]"]
  node_job_progress["Job progress<br/>[JobProgress.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
end

subgraph group_service["API and jobs"]
  node_server["Local API server<br/>[server.py]"]
  node_config_store["Local credentials<br/>[.env.example]"]
  node_output_files[("Audio and transcripts")]
  node_cli["Interactive CLI<br/>[run.py]"]
end

subgraph group_unicast["Unicast access"]
  node_auth["Unicast login<br/>[auth.py]"]
  node_session["Session cookies<br/>[auth.py]"]
  node_unicast_catalog["Course and podcast catalog<br/>[unicast.py]"]
end

subgraph group_media["Audio processing"]
  node_downloader["Podcast downloader<br/>[unicast.py]"]
  node_transcriber["Transcription engine<br/>[transcribe.py]"]
end

node_student(("Student"))
node_unicast_service{{"Unicast platform"}}
node_deepgram{{"Deepgram"}}
node_ffmpeg{{"ffmpeg"}}

node_student -->|"uses"| node_web_ui
node_web_ui -->|"renders"| node_course_picker
node_web_ui -->|"renders"| node_podcast_picker
node_web_ui -->|"opens"| node_settings
node_web_ui -->|"renders"| node_job_progress
node_web_ui -->|"requests"| node_web_api
node_job_progress -->|"reads and cancels"| node_web_api
node_settings -->|"saves settings"| node_web_api
node_web_api -->|"calls API"| node_server
node_server -->|"reads and writes"| node_config_store
node_server -->|"logs in"| node_auth
node_server -->|"lists courses"| node_unicast_catalog
node_server -.->|"lists podcasts"| node_unicast_catalog
node_server -.->|"starts job"| node_downloader
node_server -->|"transcribes audio"| node_transcriber
node_server -->|"tracks produced files"| node_output_files
node_cli -->|"checks session"| node_auth
node_cli -->|"lists podcasts"| node_unicast_catalog
node_cli -->|"downloads selections"| node_downloader
node_cli -->|"transcribes downloads"| node_transcriber
node_auth -->|"loads credentials"| node_config_store
node_auth -->|"saves cookies"| node_session
node_auth -->|"authenticates"| node_unicast_service
node_unicast_catalog -->|"loads session; reconnects"| node_auth
node_unicast_catalog -->|"fetches course data"| node_unicast_service
node_downloader -->|"fetches media links"| node_unicast_service
node_downloader -->|"uses cookies"| node_session
node_downloader -->|"writes MP3"| node_output_files
node_transcriber -->|"loads API key"| node_config_store
node_transcriber -->|"sends audio"| node_deepgram
node_transcriber -->|"converts MP4"| node_ffmpeg
node_transcriber -->|"writes transcript"| node_output_files
node_job_progress -->|"opens output folder"| node_output_files

click node_web_ui "https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/App.tsx"
click node_course_picker "https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/CoursePicker.tsx"
click node_podcast_picker "https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/PodcastPicker.tsx"
click node_settings "https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/SettingsDialog.tsx"
click node_job_progress "https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/JobProgress.tsx"
click node_web_api "https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/api.ts"
click node_server "https://github.com/nthclrd/unicast-transcript/blob/main/server.py"
click node_config_store "https://github.com/nthclrd/unicast-transcript/blob/main/.env.example"
click node_cli "https://github.com/nthclrd/unicast-transcript/blob/main/run.py"
click node_auth "https://github.com/nthclrd/unicast-transcript/blob/main/auth.py"
click node_session "https://github.com/nthclrd/unicast-transcript/blob/main/auth.py"
click node_unicast_catalog "https://github.com/nthclrd/unicast-transcript/blob/main/unicast.py"
click node_downloader "https://github.com/nthclrd/unicast-transcript/blob/main/unicast.py"
click node_transcriber "https://github.com/nthclrd/unicast-transcript/blob/main/transcribe.py"

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_web_ui,node_course_picker,node_podcast_picker,node_settings,node_job_progress,node_web_api toneBlue
class node_server,node_config_store,node_output_files,node_cli toneAmber
class node_auth,node_session,node_unicast_catalog toneMint
class node_downloader,node_transcriber toneRose
class node_student,node_unicast_service,node_deepgram,node_ffmpeg toneIndigo
```

## Components

### Local interface

- [Web workflow](https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Course picker](https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/CoursePicker.tsx): `frontend/src/components/CoursePicker.tsx`
- [Podcast selection](https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/PodcastPicker.tsx): `frontend/src/components/PodcastPicker.tsx`
- [Credentials settings](https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/SettingsDialog.tsx): `frontend/src/components/SettingsDialog.tsx`
- [Job progress](https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/components/JobProgress.tsx): `frontend/src/components/JobProgress.tsx`
- [API client](https://github.com/nthclrd/unicast-transcript/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### API and jobs

- [Local API server](https://github.com/nthclrd/unicast-transcript/blob/main/server.py): `server.py`
- [Local credentials](https://github.com/nthclrd/unicast-transcript/blob/main/.env.example): `.env.example`
- **Audio and transcripts**
- [Interactive CLI](https://github.com/nthclrd/unicast-transcript/blob/main/run.py): `run.py`

### Unicast access

- [Unicast login](https://github.com/nthclrd/unicast-transcript/blob/main/auth.py): `auth.py`
- [Session cookies](https://github.com/nthclrd/unicast-transcript/blob/main/auth.py): `auth.py`
- [Course and podcast catalog](https://github.com/nthclrd/unicast-transcript/blob/main/unicast.py): `unicast.py`

### Audio processing

- [Podcast downloader](https://github.com/nthclrd/unicast-transcript/blob/main/unicast.py): `unicast.py`
- [Transcription engine](https://github.com/nthclrd/unicast-transcript/blob/main/transcribe.py): `transcribe.py`

### Other components

- **Student**
- **Unicast platform**
- **Deepgram**
- **ffmpeg**

## Connections

- Student → Web workflow: uses (evidence: `README.md`)
- Web workflow → Course picker: renders (evidence: `frontend/src/App.tsx`)
- Web workflow → Podcast selection: renders (evidence: `frontend/src/App.tsx`)
- Web workflow → Credentials settings: opens (evidence: `frontend/src/App.tsx`)
- Web workflow → Job progress: renders (evidence: `frontend/src/App.tsx`)
- Web workflow → API client: requests (evidence: `frontend/src/App.tsx`)
- Job progress → API client: reads and cancels (evidence: `frontend/src/components/JobProgress.tsx`)
- Credentials settings → API client: saves settings (evidence: `frontend/src/components/SettingsDialog.tsx`)
- API client → Local API server: calls API (evidence: `README.md`)
- Local API server → Local credentials: reads and writes (evidence: `server.py`)
- Local API server → Unicast login: logs in (evidence: `server.py`)
- Local API server → Course and podcast catalog: lists courses (evidence: `server.py`)
- Local API server → Course and podcast catalog: lists podcasts (evidence: `server.py`)
- Local API server → Podcast downloader: starts job (evidence: `server.py`)
- Local API server → Transcription engine: transcribes audio (evidence: `server.py`)
- Local API server → Audio and transcripts: tracks produced files (evidence: `server.py`)
- Interactive CLI → Unicast login: checks session (evidence: `run.py`)
- Interactive CLI → Course and podcast catalog: lists podcasts (evidence: `run.py`)
- Interactive CLI → Podcast downloader: downloads selections (evidence: `run.py`)
- Interactive CLI → Transcription engine: transcribes downloads (evidence: `run.py`)
- Unicast login → Local credentials: loads credentials (evidence: `auth.py`)
- Unicast login → Session cookies: saves cookies (evidence: `auth.py`)
- Unicast login → Unicast platform: authenticates (evidence: `auth.py`)
- Course and podcast catalog → Unicast login: loads session; reconnects (evidence: `unicast.py`)
- Course and podcast catalog → Unicast platform: fetches course data (evidence: `unicast.py`)
- Podcast downloader → Unicast platform: fetches media links (evidence: `unicast.py`)
- Podcast downloader → Session cookies: uses cookies (evidence: `unicast.py`)
- Podcast downloader → Audio and transcripts: writes MP3 (evidence: `README.md`)
- Transcription engine → Local credentials: loads API key (evidence: `transcribe.py`)
- Transcription engine → Deepgram: sends audio (evidence: `transcribe.py`)
- Transcription engine → ffmpeg: converts MP4 (evidence: `transcribe.py`)
- Transcription engine → Audio and transcripts: writes transcript (evidence: `transcribe.py`)
- Job progress → Audio and transcripts: opens output folder (evidence: `README.md`)
