# sthpratik/whisper architecture

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

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

## Overview

##### Project Type and Purpose
- The project is a local transcription web app built using Flask (Python) for the backend and HTML/JS/CSS for the frontend.
- Its purpose is to allow users to either upload an audio/video file or record directly via a microphone so that the Whisper AI model can generate a transcription.

##### Analyzing the File Structure
- At the top-level you see configuration files (e.g., Dockerfile, docker-compose.yml, requirements.txt) which indicate containerization and dependency management.
- The src directory holds the core application code:
– Files like main.py (or possibly app.py as suggested by the README) provide the Flask web server entry point.
– audio.py likely handles audio processing and interfacing with the Whisper model.
– youtubeVideoDownloader.py indicates an additional module to download YouTube videos for transcription.
– The static and templates directories contain frontend assets (CSS, HTML) which define the user interface.
- The presence of a Jupyter notebook (whisper.ipynb) suggests that some prototyping or interactive experiments were conducted with the Whisper model.

##### Interpreting the README for Architectural Insights
- The README outlines two main user workflows: uploading an audio/video file and recording via microphone.
- It confirms the use of Flask for the backend, and that the Whisper AI model is the core transcription engine.
- It details the basic front-end flow (display status messages, process transcription results) and points out Docker for deployment.

a. Main Components
– Client (User Interface): Represented by the browser, responsible for file uploads, initiating recording, and displaying results.
– Frontend Assets: HTML templates, CSS styles, and JavaScript that manage UI interactions.
– Backend Server (Flask App): Acts as the API layer that handles HTTP requests, routes them appropriately, coordinates the transcription process, and returns status updates/results.
– Audio Processing Module: Consists of audio.py and elements within main.py that interface with the Whisper AI model to process the files or microphone input.
– External Services/Modules:
- YouTube Video Downloader – a module that downloads and preprocesses video data for transcription.
- Containerization Environment – Docker and docker-compose files indicate that components run in containers in deployment.

b. Relationships and Interactions
– The client sends a request (upload or record) to the Flask backend.
– The Flask server receives the input, forwards it to the audio processing component that utilizes the Whisper model for transcription.
– Once transcription is complete, the backend sends back status updates and the transcribed text to the client UI.
– If a YouTube video is selected, the downloader module is triggered to retrieve the video, then the audio stream is passed to the transcriber.
– Docker containers encapsulate the running environment, ensuring consistent deployment for both development and production.

c. Architectural Patterns and Design Principles
– The architecture follows a clear separation of concerns: Frontend for presentation, backend for business logic/API, and dedicated modules for audio processing.
– It is a single-page web application using RESTful HTTP interactions (file upload endpoints, status update endpoints).
– Containerization with Docker supports scalability and consistency.

d. Relevant Technologies/Frameworks
– Flask (Backend framework)
– HTML, CSS, JavaScript (Frontend)
– Whisper AI Model (Transcription engine)
– Docker (Containerization) and docker-compose (Orchestration)
– Python libraries noted in requirements.txt (for HTTP handling, audio processing, etc.)

##### Final Assembly
– Add detailed interactions between components such as file uploads, API calls, and external module invocations.
– Finally, integrate deployment aspects (Docker) to show the containerized nature of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (UI/Browser)"
        UI1["Index.html"]:::frontend
        UI2["Static Assets"]:::frontend
    end

    %% Backend Layer inside Deployment Environment
    subgraph "Application Backend"
        B["Flask Server"]:::backend
    end

    %% Processing Modules
    A["Audio Processing (Whisper Model)"]:::processing
    Y["YouTube Video Downloader"]:::processing

    %% Deployment Environment
    subgraph "Deployment Environment"
        D1["Dockerfile"]:::deployment
        D2["docker-compose.yml"]:::deployment
        D3["docker-compose.deploy.yml"]:::deployment
    end

    %% Interactions
    UI1 -->|"upload/record"| B
    UI2 -->|"upload/record"| B

    B -->|"transcription_request"| A
    A -->|"transcription_result"| B

    B -->|"download_request"| Y
    Y -->|"audio_stream"| A

    B -->|"display_transcription"| UI1

    D1 -->|"containerizes"| B
    D2 -->|"containerizes"| B
    D3 -->|"containerizes"| B

    %% Click Events
    click UI1 "https://github.com/sthpratik/whisper/blob/main/src/templates/index.html"
    click UI2 "https://github.com/sthpratik/whisper/tree/main/src/static"
    click B "https://github.com/sthpratik/whisper/blob/main/src/main.py"
    click A "https://github.com/sthpratik/whisper/blob/main/src/audio.py"
    click Y "https://github.com/sthpratik/whisper/blob/main/src/youtubeVideoDownloader.py"
    click D1 "https://github.com/sthpratik/whisper/tree/main/Dockerfile"
    click D2 "https://github.com/sthpratik/whisper/blob/main/docker-compose.yml"
    click D3 "https://github.com/sthpratik/whisper/blob/main/docker-compose.deploy.yml"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#1D9BF0,stroke-width:2px;
    classDef backend fill:#F7D6AD,stroke:#F39C12,stroke-width:2px;
    classDef processing fill:#C3F7AD,stroke:#28B463,stroke-width:2px;
    classDef deployment fill:#F7A4B9,stroke:#E74C3C,stroke-width:2px;
```
