# fluxcapacitor2/whisper-asr-webapp architecture

> Architecture diagram of the GitHub repository fluxcapacitor2/whisper-asr-webapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fluxcapacitor2/whisper-asr-webapp
- Repository: https://github.com/fluxcapacitor2/whisper-asr-webapp

## Overview

##### Project type and purpose
- This is a full-stack web application (“whisper-asr-webapp”) for automatic speech recognition, built as a single Docker container.
- Frontend: Svelte SPA (static HTML/CSS/JS) served from the same FastAPI/Uvicorn server.
- Backend: FastAPI exposes a `/transcribe` endpoint; invokes ffmpeg and OpenAI’s Whisper locally; returns JSON transcript.

##### Main components
a. Client / Browser
- UI built with Svelte (components in `frontend/src`)
- Uploads audio/video files, displays transcripts, allows downloads in various formats.
b. Static Asset Server
- Uvicorn/Starlette serves compiled Svelte build (HTML, CSS, JS) on HTTP GET /.
c. REST API Layer
- FastAPI (server.py) listens on `/transcribe` POST.
d. Transcription Pipeline (inside backend)
- ffmpeg process: normalizes and converts incoming media.
- Whisper model: loads model from local cache (Docker volume `whisper_models`), performs ASR.
e. Data store / Cache
- Docker volume mounted at `/root/.cache/whisper` for model files.
f. Docker Container / Host
- Single container running Uvicorn + FastAPI + static assets + Whisper + ffmpeg.

##### Relationships and data flow
1. User opens Browser → HTTP GET `/` → Static assets served.
2. User selects file & settings (model, language) → Browser sends POST `/transcribe` with file + parameters.
3. FastAPI receives request → pipes file into ffmpeg → ffmpeg outputs a normalized audio stream.
4. Whisper library loads model from local cache → processes stream → generates transcription with optional timestamps.
5. FastAPI packages result into JSON → returns HTTP response to Browser.
6. Browser renders transcript in UI; user may download in TXT, SRT, VTT, TSV, JSON.

##### Architectural patterns and design principles
- Client-Server (SPA + REST API)
- Single container “micro-mono” deployment (frontend + backend in one).
- Separation of concerns: UI vs. processing pipeline.
- Reuse of external tools (ffmpeg) and models (Whisper) via simple process piping.

##### Relevant technologies/frameworks
- Frontend: Svelte, Vite, Tailwind CSS
- Backend: FastAPI, Uvicorn, Python 3.11 (pyproject.toml)
- Media processing: ffmpeg CLI, OpenAI Whisper Python package
- Containerization: Dockerfile, `run.sh`, GitHub Actions (docker.yml)
- Volume management for Whisper model cache

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser (Svelte UI)"
        direction TB
        Entry["main.ts"]:::frontend
        App["App.svelte"]:::frontend
        Components["components"]:::frontend
        Types["WhisperResult.ts"]:::frontend
        Utils["utils"]:::frontend
        ViteConfig["vite.config.ts"]:::frontend
        SvelteConfig["svelte.config.js"]:::frontend
        TailwindConfig["tailwind.config.js"]:::frontend
        Public["public"]:::frontend
    end

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB
        Static["Static Asset Server\n(Uvicorn/Starlette)"]:::backend
        API["FastAPI Server\n(server.py)"]:::backend

        subgraph "Transcription Pipeline"
            direction TB
            FFmpeg["ffmpeg CLI"]:::external
            Whisper["Whisper Model"]:::ml
        end

        Volume["Model Cache\n(/root/.cache/whisper)"]:::volume
    end

    %% CI/CD Outside
    CI["GitHub Actions\nCI/CD"]:::ci

    %% Data Flows
    Entry -->|"bundle → HTML/CSS/JS"| Static
    App --> Static
    Components --> Static
    Types --> Static
    Utils --> Static
    ViteConfig --> Static
    SvelteConfig --> Static
    TailwindConfig --> Static
    Public --> Static

    Static -->|"GET /"| Entry

    Entry -->|"POST /transcribe\n(audio + params)"| API
    Components --> API
    Utils --> API

    API -->|"pipe file"| FFmpeg
    FFmpeg -->|"normalized audio"| Whisper
    Whisper -->|"transcript JSON"| API
    API -->|"JSON transcript"| App

    CI -->|"build & push image"| Docker

    %% Click Events
    click Entry "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/src/main.ts"
    click App "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/src/App.svelte"
    click Components "https://github.com/fluxcapacitor2/whisper-asr-webapp/tree/main/frontend/src/components"
    click Types "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/src/types/WhisperResult.ts"
    click Utils "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/src/utils/convert.ts"
    click Utils "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/src/utils/utils.ts"
    click ViteConfig "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/vite.config.ts"
    click SvelteConfig "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/svelte.config.js"
    click TailwindConfig "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/frontend/tailwind.config.js"
    click Public "https://github.com/fluxcapacitor2/whisper-asr-webapp/tree/main/frontend/public"
    click API "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/backend/server.py"
    click Volume "https://github.com/fluxcapacitor2/whisper-asr-webapp/tree/main//root/.cache/whisper"
    click CI "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/.github/workflows/docker.yml"
    click Dockerfile "https://github.com/fluxcapacitor2/whisper-asr-webapp/tree/main/Dockerfile"
    click RunSh "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/run.sh"
    click DockerIgnore "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/backend/.dockerignore"
    click PyProject "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/backend/pyproject.toml"
    click GitIgnore "https://github.com/fluxcapacitor2/whisper-asr-webapp/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#D6F5D6,stroke:#238823,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px
    classDef ml fill:#FFE7C2,stroke:#CC8400,stroke-width:1px
    classDef volume fill:#E8E8E8,stroke:#999999,stroke-width:1px
    classDef ci fill:#FFF3BF,stroke:#D9A000,stroke-width:1px
```
