# jimmykoumako/whisper architecture

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

- Interactive diagram: https://gitdiagram.com/jimmykoumako/whisper
- Repository: https://github.com/jimmykoumako/whisper

## Overview

Whisper Studio is a local speech-to-text and AI knowledge platform. Its main workflow accepts uploaded or linked media, transcribes it through a selectable Whisper backend, and keeps transcripts and metadata in a searchable SQLite library. Users can then request Ollama summaries, questions, chapters, reference extraction, or study notes, and export transcripts in several formats. The graph also shows the web/API entry points and desktop control capability. Several modules were not sampled, so their internal call wiring is left out where the excerpts do not establish it.

Main entry points: [`api_v1.py`](https://github.com/jimmykoumako/whisper/blob/master/api_v1.py) (HTTP API), [`web.py`](https://github.com/jimmykoumako/whisper/blob/master/web.py) (Web UI), [`transcription_service.py`](https://github.com/jimmykoumako/whisper/blob/master/transcription_service.py) (Media intake), [`database.py`](https://github.com/jimmykoumako/whisper/blob/master/database.py) (Transcript database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_web["Web UI<br/>[web.py]"]
  node_api["HTTP API<br/>[api_v1.py]"]
  node_auth["API key auth<br/>[auth.py]"]
end

subgraph group_transcription["Media transcription"]
  node_transcription_service["Media intake"]
  node_jobs["Transcription jobs<br/>[jobs.py]"]
  node_backend_factory["Backend selection<br/>[factory.py]"]
  node_backend["Whisper backends"]
end

subgraph group_library["Transcript library"]
  node_sqlite[("Transcript database<br/>[database.py]")]
  node_uploads[("Audio files<br/>[storage.py]")]
  node_search["Transcript search<br/>[database.py]"]
end

subgraph group_analysis["AI and outputs"]
  node_ai_service["AI analysis<br/>[ai.py]"]
  node_ollama_service["Ollama client<br/>[ollama.py]"]
  node_exports["Transcript exports<br/>[exports.py]"]
end

subgraph group_operations["Studio operations"]
  node_control["Studio controls<br/>[control.py]"]
  node_ngrok["Public tunnel<br/>[ngrok_utils.py]"]
end

node_user(("Studio user"))
node_api_client(("API client"))
node_media_source(("Media source"))
node_ollama{{"Ollama model"}}

node_user -->|"uses"| node_web
node_api_client -->|"calls"| node_api
node_api -->|"checks keys"| node_auth
node_api -->|"requests intake"| node_transcription_service
node_web -->|"submits media"| node_transcription_service
node_media_source -->|"provides media"| node_transcription_service
node_transcription_service -->|"stores audio"| node_uploads
node_transcription_service -->|"creates records"| node_sqlite
node_transcription_service -->|"schedules work"| node_jobs
node_jobs -->|"selects backend"| node_backend_factory
node_backend_factory -->|"creates backend"| node_backend
node_jobs -->|"transcribes audio"| node_backend
node_jobs -->|"saves results"| node_sqlite
node_api -->|"requests analysis"| node_ai_service
node_web -->|"requests analysis"| node_ai_service
node_ai_service -->|"generates prompts"| node_ollama_service
node_ollama_service -->|"sends requests"| node_ollama
node_api -->|"searches transcripts"| node_search
node_web -->|"searches transcripts"| node_search
node_search -->|"reads transcripts"| node_sqlite
node_api -->|"requests exports"| node_exports
node_web -->|"requests exports"| node_exports
node_api -->|"reads library"| node_sqlite
node_web -->|"reads library"| node_sqlite
node_user -->|"manages studio"| node_control
node_control -.->|"controls tunnel"| node_ngrok

click node_web "https://github.com/jimmykoumako/whisper/blob/master/web.py"
click node_api "https://github.com/jimmykoumako/whisper/blob/master/api_v1.py"
click node_auth "https://github.com/jimmykoumako/whisper/blob/master/auth.py"
click node_transcription_service "https://github.com/jimmykoumako/whisper/blob/master/transcription_service.py"
click node_jobs "https://github.com/jimmykoumako/whisper/blob/master/jobs.py"
click node_backend_factory "https://github.com/jimmykoumako/whisper/blob/master/backends/factory.py"
click node_backend "https://github.com/jimmykoumako/whisper/tree/master/backends"
click node_sqlite "https://github.com/jimmykoumako/whisper/blob/master/database.py"
click node_uploads "https://github.com/jimmykoumako/whisper/blob/master/storage.py"
click node_search "https://github.com/jimmykoumako/whisper/blob/master/database.py"
click node_ai_service "https://github.com/jimmykoumako/whisper/blob/master/services/ai.py"
click node_ollama_service "https://github.com/jimmykoumako/whisper/blob/master/services/ollama.py"
click node_exports "https://github.com/jimmykoumako/whisper/blob/master/exports.py"
click node_control "https://github.com/jimmykoumako/whisper/blob/master/services/control.py"
click node_ngrok "https://github.com/jimmykoumako/whisper/blob/master/ngrok_utils.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,node_api,node_auth,node_user,node_api_client toneBlue
class node_transcription_service,node_jobs,node_backend_factory,node_backend toneAmber
class node_sqlite,node_uploads,node_search toneMint
class node_ai_service,node_ollama_service,node_exports toneRose
class node_control,node_ngrok,node_media_source,node_ollama toneIndigo
```

## Components

### User interfaces

- [Web UI](https://github.com/jimmykoumako/whisper/blob/master/web.py): `web.py`
- [HTTP API](https://github.com/jimmykoumako/whisper/blob/master/api_v1.py): `api_v1.py`
- [API key auth](https://github.com/jimmykoumako/whisper/blob/master/auth.py): `auth.py`

### Media transcription

- [Media intake](https://github.com/jimmykoumako/whisper/blob/master/transcription_service.py): `transcription_service.py`
- [Transcription jobs](https://github.com/jimmykoumako/whisper/blob/master/jobs.py): `jobs.py`
- [Backend selection](https://github.com/jimmykoumako/whisper/blob/master/backends/factory.py): `backends/factory.py`
- [Whisper backends](https://github.com/jimmykoumako/whisper/tree/master/backends): `backends`

### Transcript library

- [Transcript database](https://github.com/jimmykoumako/whisper/blob/master/database.py): `database.py`
- [Audio files](https://github.com/jimmykoumako/whisper/blob/master/storage.py): `storage.py`
- [Transcript search](https://github.com/jimmykoumako/whisper/blob/master/database.py): `database.py`

### AI and outputs

- [AI analysis](https://github.com/jimmykoumako/whisper/blob/master/services/ai.py): `services/ai.py`
- [Ollama client](https://github.com/jimmykoumako/whisper/blob/master/services/ollama.py): `services/ollama.py`
- [Transcript exports](https://github.com/jimmykoumako/whisper/blob/master/exports.py): `exports.py`

### Studio operations

- [Studio controls](https://github.com/jimmykoumako/whisper/blob/master/services/control.py): `services/control.py`
- [Public tunnel](https://github.com/jimmykoumako/whisper/blob/master/ngrok_utils.py): `ngrok_utils.py`

### Other components

- **Studio user**
- **API client**
- **Media source**
- **Ollama model**

## Connections

- Studio user → Web UI: uses
- API client → HTTP API: calls
- HTTP API → API key auth: checks keys
- HTTP API → Media intake: requests intake
- Web UI → Media intake: submits media
- Media source → Media intake: provides media
- Media intake → Audio files: stores audio
- Media intake → Transcript database: creates records
- Media intake → Transcription jobs: schedules work
- Transcription jobs → Backend selection: selects backend
- Backend selection → Whisper backends: creates backend
- Transcription jobs → Whisper backends: transcribes audio
- Transcription jobs → Transcript database: saves results
- HTTP API → AI analysis: requests analysis
- Web UI → AI analysis: requests analysis
- AI analysis → Ollama client: generates prompts
- Ollama client → Ollama model: sends requests
- HTTP API → Transcript search: searches transcripts
- Web UI → Transcript search: searches transcripts
- Transcript search → Transcript database: reads transcripts
- HTTP API → Transcript exports: requests exports
- Web UI → Transcript exports: requests exports
- HTTP API → Transcript database: reads library
- Web UI → Transcript database: reads library
- Studio user → Studio controls: manages studio
- Studio controls → Public tunnel: controls tunnel