# ahmetoner/whisper-asr-webservice architecture

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

- Interactive diagram: https://gitdiagram.com/ahmetoner/whisper-asr-webservice
- Repository: https://github.com/ahmetoner/whisper-asr-webservice

## Overview

##### Project Type and Purpose
- Type: A containerized RESTful microservice for Automatic Speech Recognition (ASR).
- Purpose: Expose multiple Whisper-based ASR engines (OpenAI Whisper, Faster-Whisper, WhisperX) over HTTP with configurable audio formats, output formats, and hardware acceleration (CPU/GPU).

##### File Structure to Extract Major Components
Top-level artifacts:
- Dockerfile / docker-compose.yml / GPU variant – packaging & orchestration
- app/webservice.py – entrypoint for the HTTP API (likely FastAPI or Flask + Swagger)
- app/config.py – environment-driven configuration
- app/factory/asr_model_factory.py – factory that selects and loads the appropriate ASR engine
- app/asr_models/*.py – concrete engine implementations (OpenAI, Faster Whisper, WhisperX)
- app/utils.py – helpers (e.g., audio pre-processing, VAD)
- cache persistence via host-volume for model downloads
- docs + mkdocs.yml – documentation site generation

##### Key Insights from README
- REST API with Swagger UI (http://host:9000)
- Supports multiple input formats (via FFmpeg) and multiple output formats (text, JSON, VTT, SRT, TSV)
- Environment variables control engine/model/device/timeout
- Docker images for CPU and GPU, Docker Compose examples

##### Main Components
A. Client Layer
– “API Consumer” (curl, browser, SDKs)

B. API Layer
– HTTP server (uvicorn/gunicorn + FastAPI or Flask)
– Swagger UI / OpenAPI docs

C. Configuration Module
– Reads ENV variables (ASR_ENGINE, ASR_MODEL, DEVICE, MODEL_IDLE_TIMEOUT, etc.)

D. ASR Model Factory
– Implements the factory pattern: inspects config, returns instance of the chosen engine

E. ASR Engine Implementations
– OpenAI Whisper Engine
– Faster-Whisper Engine
– WhisperX Engine (with optional speaker diarization)

F. Audio/Video Processing
– FFmpeg subprocess wrapper for format conversion

G. Model Storage & Cache
– Local cache directory (persisted via Docker volume)
– On-demand download from model repositories (Hugging Face / OpenAI)

H. Hardware Resources
– CPU and/or GPU
– CUDA runtime for GPU containers

I. Containerization & Orchestration
– Docker image (Dockerfile, GPU variant)
– docker-compose.yml (multi-service setup for future expansions, caching volume)

##### Relationships & Data Flow
1. Client → HTTP request (POST /transcribe)
2. API Layer parses request, handles authentication (if any)
3. API calls Configuration Module → ASR Model Factory
4. Factory checks cache → loads model into memory on CPU/GPU
5. API Layer streams audio to FFmpeg wrapper → normalized PCM data
6. Engine Implementation processes audio → emits transcription + timestamps
7. API Layer formats output (JSON/VTT/SRT/TSV/text)
8. Response returned to Client
9. Model may remain loaded until IDLE_TIMEOUT → then factory unloads

##### Architectural Patterns & Principles
- Factory Pattern for pluggable ASR engines
- Separation of concerns: API vs. model logic vs. utils vs. config
- Containerized infrastructure for portability (Docker, Compose)
- Use of environment variables for 12-factor compliance
- Extensibility: drop-in new ASR engines by adding to app/asr_models + factory

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["API Consumer\n(curl, browser, SDKs)"]:::external

    %% Dockerized Microservice Boundary
    subgraph "Docker Container\n(CPU/GPU with CUDA)" 
        direction TB
        API["API Layer\n(app/webservice.py)"]:::api
        Config["Configuration Module\n(app/config.py)"]:::api
        Factory["ASR Model Factory\n(app/factory/asr_model_factory.py)"]:::model
        BaseModel["ASR Model Base Class\n(app/asr_models/asr_model.py)"]:::model
        OAI["OpenAI Whisper Engine\n(app/asr_models/openai_whisper_engine.py)"]:::model
        FW["Faster-Whisper Engine\n(app/asr_models/faster_whisper_engine.py)"]:::model
        WX["WhisperX Engine\n(app/asr_models/mbain_whisperx_engine.py)"]:::model
        Utils["Audio/Video Processing\n(app/utils.py)"]:::external
        Cache["Model Cache Volume"]:::storage
        Repo["Model Repositories\n(Hugging Face / OpenAI)"]:::external
    end

    %% Orchestration Files
    subgraph "Orchestration Files" 
        direction TB
        DCpu["Dockerfile"]:::infra
        DGpu["Dockerfile.gpu"]:::infra
        ComposeCPU["docker-compose.yml"]:::infra
        ComposeGPU["docker-compose.gpu.yml"]:::infra
    end

    %% Data Flow
    Client -->|POST /transcribe| API
    API -->|reads ENV vars| Config
    API -->|calls factory| Factory
    Factory -->|checks cache| Cache
    Factory -->|downloads if missing| Repo
    Factory -->|returns ASRModel instance| BaseModel
    BaseModel -->|implements| OAI
    BaseModel -->|implements| FW
    BaseModel -->|implements| WX
    API -->|streams audio| Utils
    Utils -->|normalized PCM| BaseModel
    BaseModel -->|transcript| API
    API -->|formats output| Client

    %% Click Events
    click API "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/webservice.py"
    click Config "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/config.py"
    click Factory "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/factory/asr_model_factory.py"
    click BaseModel "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/asr_models/asr_model.py"
    click OAI "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/asr_models/openai_whisper_engine.py"
    click FW "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/asr_models/faster_whisper_engine.py"
    click WX "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/asr_models/mbain_whisperx_engine.py"
    click Utils "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/app/utils.py"
    click DCpu "https://github.com/ahmetoner/whisper-asr-webservice/tree/main/Dockerfile"
    click DGpu "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/Dockerfile.gpu"
    click ComposeCPU "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/docker-compose.yml"
    click ComposeGPU "https://github.com/ahmetoner/whisper-asr-webservice/blob/main/docker-compose.gpu.yml"

    %% Styling
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef api fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef model fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef infra fill:#d3d3d3,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
```
