# lo-kith/captionflow architecture

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

- Interactive diagram: https://gitdiagram.com/lo-kith/captionflow
- Repository: https://github.com/lo-kith/captionflow

## Overview

CaptionFlow is a browser-based video subtitling product. Its primary workflow is upload and validation, audio extraction and Whisper transcription, interactive subtitle editing and preview, then subtitle-file or burned-video export. The graph includes the editor’s state and interaction layer as well as the documented processing and export stages. Some implementation files were not excerpted; relationships for those parts are included only where the README or source index supports them.

Main entry points: [`app/editor/page.tsx`](https://github.com/lo-kith/captionflow/blob/main/app/editor/page.tsx) (Editor workspace), [`store/editorStore.ts`](https://github.com/lo-kith/captionflow/blob/main/store/editorStore.ts) (Editor state), [`components/export/ExportDialog.tsx`](https://github.com/lo-kith/captionflow/blob/main/components/export/ExportDialog.tsx) (Export options), [`components/upload/UploadZone.tsx`](https://github.com/lo-kith/captionflow/blob/main/components/upload/UploadZone.tsx) (Upload zone)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Video processing"]
  node_upload_ui["Upload zone<br/>[UploadZone.tsx]"]
  node_upload_api["Upload validation<br/>[route.ts]"]
  node_metadata["Video metadata<br/>[getMetadata.ts]"]
  node_transcribe_api["Transcription route<br/>[route.ts]"]
  node_audio_extract["Audio extraction<br/>[extractAudio.ts]"]
  node_whisper["Whisper provider<br/>[whisper.ts]"]
  node_transcription_contract["Provider contract<br/>[service.ts]"]
end

subgraph group_editor["Subtitle editor"]
  node_editor_page["Editor workspace<br/>[page.tsx]"]
  node_video_player["Video preview<br/>[VideoPlayer.tsx]"]
  node_subtitle_editor["Subtitle editor<br/>[SubtitleEditor.tsx]"]
  node_timeline["Subtitle timeline<br/>[Timeline.tsx]"]
  node_timeline_controls["Timeline controls"]
  node_style_panel["Caption styling<br/>[StylePanel.tsx]"]
  node_shortcuts["Keyboard shortcuts"]
  node_editor_store["Editor state<br/>[editorStore.ts]"]
end

subgraph group_export["Export pipeline"]
  node_export_dialog["Export options<br/>[ExportDialog.tsx]"]
  node_srt["SRT formatter<br/>[srt.ts]"]
  node_vtt["VTT formatter<br/>[vtt.ts]"]
  node_export_api["Video export route<br/>[route.ts]"]
  node_burn["Subtitle burn-in<br/>[burnSubtitles.ts]"]
  node_download_api["Video download<br/>[route.ts]"]
end

subgraph group_shared["Shared runtime"]
  node_subtitle_utils["Subtitle operations<br/>[utils.ts]"]
  node_temp_files[("Temporary files<br/>[tempFiles.ts]")]
end

node_user(("Video editor"))

node_user -->|"selects video"| node_upload_ui
node_upload_ui -->|"uploads video"| node_upload_api
node_upload_api -->|"reads metadata"| node_metadata
node_upload_api -->|"stores upload"| node_temp_files
node_upload_ui -->|"requests transcription"| node_transcribe_api
node_transcribe_api -->|"extracts audio"| node_audio_extract
node_transcribe_api -->|"transcribes audio"| node_whisper
node_whisper -->|"implements"| node_transcription_contract
node_transcribe_api -->|"manages audio files"| node_temp_files
node_upload_ui -->|"opens editor"| node_editor_page
node_editor_page -->|"renders"| node_video_player
node_editor_page -->|"renders"| node_subtitle_editor
node_editor_page -->|"renders"| node_timeline
node_editor_page -->|"renders"| node_timeline_controls
node_editor_page -->|"renders"| node_style_panel
node_editor_page -->|"opens"| node_export_dialog
node_editor_page -->|"registers"| node_shortcuts
node_video_player -->|"reads and updates"| node_editor_store
node_subtitle_editor -->|"edits state"| node_editor_store
node_timeline -->|"edits state"| node_editor_store
node_timeline_controls -.->|"controls playback"| node_editor_store
node_style_panel -->|"updates style"| node_editor_store
node_shortcuts -->|"dispatches actions"| node_editor_store
node_editor_store -->|"uses operations"| node_subtitle_utils
node_export_dialog -->|"reads export state"| node_editor_store
node_export_dialog -->|"generates SRT"| node_srt
node_export_dialog -->|"generates VTT"| node_vtt
node_export_dialog -->|"requests video export"| node_export_api
node_export_api -->|"renders captions"| node_burn
node_export_api -->|"manages export files"| node_temp_files
node_burn -->|"formats subtitles"| node_srt
node_export_api -.->|"returns output path"| node_download_api
node_user -->|"downloads video"| node_download_api

click node_upload_ui "https://github.com/lo-kith/captionflow/blob/main/components/upload/UploadZone.tsx"
click node_upload_api "https://github.com/lo-kith/captionflow/blob/main/app/api/upload/route.ts"
click node_metadata "https://github.com/lo-kith/captionflow/blob/main/lib/ffmpeg/getMetadata.ts"
click node_transcribe_api "https://github.com/lo-kith/captionflow/blob/main/app/api/transcribe/route.ts"
click node_audio_extract "https://github.com/lo-kith/captionflow/blob/main/lib/ffmpeg/extractAudio.ts"
click node_whisper "https://github.com/lo-kith/captionflow/blob/main/lib/transcription/whisper.ts"
click node_transcription_contract "https://github.com/lo-kith/captionflow/blob/main/lib/transcription/service.ts"
click node_editor_page "https://github.com/lo-kith/captionflow/blob/main/app/editor/page.tsx"
click node_video_player "https://github.com/lo-kith/captionflow/blob/main/components/video/VideoPlayer.tsx"
click node_subtitle_editor "https://github.com/lo-kith/captionflow/blob/main/components/editor/SubtitleEditor.tsx"
click node_timeline "https://github.com/lo-kith/captionflow/blob/main/components/editor/Timeline.tsx"
click node_timeline_controls "https://github.com/lo-kith/captionflow/blob/main/components/editor/TimelineControls.tsx"
click node_style_panel "https://github.com/lo-kith/captionflow/blob/main/components/editor/StylePanel.tsx"
click node_shortcuts "https://github.com/lo-kith/captionflow/blob/main/hooks/useKeyboardShortcuts.ts"
click node_editor_store "https://github.com/lo-kith/captionflow/blob/main/store/editorStore.ts"
click node_subtitle_utils "https://github.com/lo-kith/captionflow/blob/main/lib/subtitles/utils.ts"
click node_export_dialog "https://github.com/lo-kith/captionflow/blob/main/components/export/ExportDialog.tsx"
click node_srt "https://github.com/lo-kith/captionflow/blob/main/lib/subtitles/srt.ts"
click node_vtt "https://github.com/lo-kith/captionflow/blob/main/lib/subtitles/vtt.ts"
click node_export_api "https://github.com/lo-kith/captionflow/blob/main/app/api/export/route.ts"
click node_burn "https://github.com/lo-kith/captionflow/blob/main/lib/ffmpeg/burnSubtitles.ts"
click node_download_api "https://github.com/lo-kith/captionflow/blob/main/app/api/download/%5Bid%5D/route.ts"
click node_temp_files "https://github.com/lo-kith/captionflow/blob/main/lib/utils/tempFiles.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_upload_ui,node_upload_api,node_metadata,node_transcribe_api,node_audio_extract,node_whisper,node_transcription_contract toneBlue
class node_editor_page,node_video_player,node_subtitle_editor,node_timeline,node_timeline_controls,node_style_panel,node_shortcuts,node_editor_store toneAmber
class node_export_dialog,node_srt,node_vtt,node_export_api,node_burn,node_download_api toneMint
class node_subtitle_utils,node_temp_files toneRose
class node_user toneIndigo
```

## Components

### Video processing

- [Upload zone](https://github.com/lo-kith/captionflow/blob/main/components/upload/UploadZone.tsx): `components/upload/UploadZone.tsx`
- [Upload validation](https://github.com/lo-kith/captionflow/blob/main/app/api/upload/route.ts): `app/api/upload/route.ts`
- [Video metadata](https://github.com/lo-kith/captionflow/blob/main/lib/ffmpeg/getMetadata.ts): `lib/ffmpeg/getMetadata.ts`
- [Transcription route](https://github.com/lo-kith/captionflow/blob/main/app/api/transcribe/route.ts): `app/api/transcribe/route.ts`
- [Audio extraction](https://github.com/lo-kith/captionflow/blob/main/lib/ffmpeg/extractAudio.ts): `lib/ffmpeg/extractAudio.ts`
- [Whisper provider](https://github.com/lo-kith/captionflow/blob/main/lib/transcription/whisper.ts): `lib/transcription/whisper.ts`
- [Provider contract](https://github.com/lo-kith/captionflow/blob/main/lib/transcription/service.ts): `lib/transcription/service.ts`

### Subtitle editor

- [Editor workspace](https://github.com/lo-kith/captionflow/blob/main/app/editor/page.tsx): `app/editor/page.tsx`
- [Video preview](https://github.com/lo-kith/captionflow/blob/main/components/video/VideoPlayer.tsx): `components/video/VideoPlayer.tsx`
- [Subtitle editor](https://github.com/lo-kith/captionflow/blob/main/components/editor/SubtitleEditor.tsx): `components/editor/SubtitleEditor.tsx`
- [Subtitle timeline](https://github.com/lo-kith/captionflow/blob/main/components/editor/Timeline.tsx): `components/editor/Timeline.tsx`
- [Timeline controls](https://github.com/lo-kith/captionflow/blob/main/components/editor/TimelineControls.tsx): `components/editor/TimelineControls.tsx`
- [Caption styling](https://github.com/lo-kith/captionflow/blob/main/components/editor/StylePanel.tsx): `components/editor/StylePanel.tsx`
- [Keyboard shortcuts](https://github.com/lo-kith/captionflow/blob/main/hooks/useKeyboardShortcuts.ts): `hooks/useKeyboardShortcuts.ts`
- [Editor state](https://github.com/lo-kith/captionflow/blob/main/store/editorStore.ts): `store/editorStore.ts`

### Export pipeline

- [Export options](https://github.com/lo-kith/captionflow/blob/main/components/export/ExportDialog.tsx): `components/export/ExportDialog.tsx`
- [SRT formatter](https://github.com/lo-kith/captionflow/blob/main/lib/subtitles/srt.ts): `lib/subtitles/srt.ts`
- [VTT formatter](https://github.com/lo-kith/captionflow/blob/main/lib/subtitles/vtt.ts): `lib/subtitles/vtt.ts`
- [Video export route](https://github.com/lo-kith/captionflow/blob/main/app/api/export/route.ts): `app/api/export/route.ts`
- [Subtitle burn-in](https://github.com/lo-kith/captionflow/blob/main/lib/ffmpeg/burnSubtitles.ts): `lib/ffmpeg/burnSubtitles.ts`
- [Video download](https://github.com/lo-kith/captionflow/blob/main/app/api/download/%5Bid%5D/route.ts): `app/api/download/[id]/route.ts`

### Shared runtime

- [Subtitle operations](https://github.com/lo-kith/captionflow/blob/main/lib/subtitles/utils.ts): `lib/subtitles/utils.ts`
- [Temporary files](https://github.com/lo-kith/captionflow/blob/main/lib/utils/tempFiles.ts): `lib/utils/tempFiles.ts`

### Other components

- **Video editor**

## Connections

- Video editor → Upload zone: selects video (evidence: `README.md`)
- Upload zone → Upload validation: uploads video (evidence: `components/upload/UploadZone.tsx`)
- Upload validation → Video metadata: reads metadata (evidence: `app/api/upload/route.ts`)
- Upload validation → Temporary files: stores upload (evidence: `app/api/upload/route.ts`)
- Upload zone → Transcription route: requests transcription (evidence: `components/upload/UploadZone.tsx`)
- Transcription route → Audio extraction: extracts audio (evidence: `app/api/transcribe/route.ts`)
- Transcription route → Whisper provider: transcribes audio (evidence: `app/api/transcribe/route.ts`)
- Whisper provider → Provider contract: implements (evidence: `README.md`)
- Transcription route → Temporary files: manages audio files (evidence: `app/api/transcribe/route.ts`)
- Upload zone → Editor workspace: opens editor (evidence: `README.md`)
- Editor workspace → Video preview: renders (evidence: `app/editor/page.tsx`)
- Editor workspace → Subtitle editor: renders (evidence: `app/editor/page.tsx`)
- Editor workspace → Subtitle timeline: renders (evidence: `app/editor/page.tsx`)
- Editor workspace → Timeline controls: renders (evidence: `app/editor/page.tsx`)
- Editor workspace → Caption styling: renders (evidence: `app/editor/page.tsx`)
- Editor workspace → Export options: opens (evidence: `app/editor/page.tsx`)
- Editor workspace → Keyboard shortcuts: registers (evidence: `app/editor/page.tsx`)
- Video preview → Editor state: reads and updates (evidence: `components/video/VideoPlayer.tsx`)
- Subtitle editor → Editor state: edits state (evidence: `app/editor/page.tsx`)
- Subtitle timeline → Editor state: edits state (evidence: `components/editor/Timeline.tsx`)
- Timeline controls → Editor state: controls playback
- Caption styling → Editor state: updates style (evidence: `components/editor/StylePanel.tsx`)
- Keyboard shortcuts → Editor state: dispatches actions (evidence: `hooks/useKeyboardShortcuts.ts`)
- Editor state → Subtitle operations: uses operations (evidence: `store/editorStore.ts`)
- Export options → Editor state: reads export state (evidence: `components/export/ExportDialog.tsx`)
- Export options → SRT formatter: generates SRT (evidence: `components/export/ExportDialog.tsx`)
- Export options → VTT formatter: generates VTT (evidence: `components/export/ExportDialog.tsx`)
- Export options → Video export route: requests video export (evidence: `components/export/ExportDialog.tsx`)
- Video export route → Subtitle burn-in: renders captions (evidence: `app/api/export/route.ts`)
- Video export route → Temporary files: manages export files (evidence: `app/api/export/route.ts`)
- Subtitle burn-in → SRT formatter: formats subtitles (evidence: `lib/ffmpeg/burnSubtitles.ts`)
- Video export route → Video download: returns output path
- Video editor → Video download: downloads video (evidence: `README.md`)
