# thanhphamtmu/django-vosk-autotranscriber architecture

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

- Interactive diagram: https://gitdiagram.com/thanhphamtmu/django-vosk-autotranscriber
- Repository: https://github.com/thanhphamtmu/django-vosk-autotranscriber

## Overview

##### Project type and purpose
- This is a full-stack web application and REST API built with Django 4.x, Django REST Framework, and Django Channels.
- Its purpose is to accept user-uploaded audio files, transcode/process them via FFMPEG and VOSK (Vietnamese speech recognition), store the transcripts in a database, and present the results through a web UI, a JWT-secured API, and realtime WebSocket updates.

##### File structure
- Top-level “manage.py”, “requirements.txt”, “myproject” folder (Django settings/URLs/ASGI/WGSI).
- App folder “speech” contains views, serializers, models, forms, admin, routing, consumers, templates, utils (vosk_utils).
- “media/uploads” holds uploaded audio.
- Configuration files: settings.py includes DRF, Channels, JWT, and media settings.
- No explicit task queue—processing likely triggered synchronously in views or consumers.

##### Key insights from README
- Core modules: vosk_utils.py (speech recognition logic), views.py (upload/list/export endpoints), consumers.py (WebSocket real-time updates), serializers.py (REST API), routing.py (WS routing).
- External dependencies: VOSK models folder, FFMPEG binary, ReportLab for PDF export.
- JWT-protected API endpoints at /api/audio/. Web UI at /upload/, /list/, /export.

##### Main components
a. Clients
- Web browser (UI)
- Third-party consumer (REST API client)
- WebSocket client (within UI or standalone)
b. Application server
- Django HTTP server (Django views & DRF views)
- Django Channels ASGI server (WebSocket consumer)
c. Business logic modules
- File upload & form handling (forms.py / views.py)
- Audio conversion/transcoding (FFMPEG invoked in vosk_utils)
- Speech recognition engine (VOSK via vosk_utils.py)
- Export generator (ReportLab for PDF, plain text)
d. Data layer
- Relational database (models.py, migrations)
- File storage (media/uploads directory)
e. Integration points / external services
- Local FFMPEG binary
- VOSK model files
- JWT Auth provider (SimpleJWT library)

##### Relationships and data flow
1. User/browser sends HTTP POST to Django HTTP server →
- Django form or DRF serializer validates/stores uploaded file to media/uploads →
- Django calls vosk_utils: FFMPEG transcodes → VOSK processes audio → transcript returned.
2. Transcript + metadata saved in DB.
3. Server sends realtime update on WebSocket channel group “audio” via Django Channels consumer → Browser receives update.
4. User/browser or third-party GETs transcripts via REST API (/api/audio/) using JWT token.
5. For export, client hits /export/txt/ or /export/pdf/, Django view generates file via ReportLab or text writer, returns download.

##### Architectural patterns and principles
- Layered architecture: presentation (views/consumers), business logic (vosk_utils), data access (models), external integration (FFMPEG, VOSK).
- Separation of concerns: distinct modules for HTTP vs. WebSocket, forms vs. serializers, synchronous processing vs. realtime notification.
- Stateless API with JWT authentication.
- Shared media directory for persistence of audio.

##### Final checklist
- [ ] All main components present and labeled
- [ ] Architectural boundary grouping (e.g., “App Server”)
- [ ] Notes on JWT authentication path for API
- [ ] Realtime WebSocket update flow clearly illustrated
- [ ] External dependencies (FFMPEG, VOSK models) shown outside core app

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef client fill:#D8BFD8,stroke:#663399,color:#000;
    classDef app fill:#ADD8E6,stroke:#1E90FF,color:#000;
    classDef data fill:#98FB98,stroke:#228B22,color:#000;
    classDef external fill:#FFA500,stroke:#FF8C00,color:#000;

    subgraph Clients
        Browser["Web Browser (UI)"]:::client
        APIClient["REST API Client"]:::client
        WSClient["WebSocket Client"]:::client
    end

    subgraph "Application Server"
        subgraph "Django HTTP Server"
            Views["speech/views.py"]:::app
            Forms["speech/forms.py"]:::app
            URLsHTTP["speech/urls.py"]:::app
            TemplatesUpload["upload.html"]:::app
            TemplatesList["list.html"]:::app
        end
        subgraph "REST API (DRF)"
            Serializers["speech/serializers.py"]:::app
            URLsAPI["speech/urls.py"]:::app
            JWTConfig["settings.py (JWT)"]:::app
        end
        subgraph "WebSocket (Channels)"
            Consumers["speech/consumers.py"]:::app
            RoutingWS["speech/routing.py"]:::app
            ASGI["myproject/asgi.py"]:::app
        end
        Logic["speech/vosk_utils.py"]:::app
        Settings["myproject/settings.py"]:::app
        URLsProject["myproject/urls.py"]:::app
        ASGIProject["myproject/asgi.py"]:::app
        WSGI["myproject/wsgi.py"]:::app
        manage["manage.py"]:::app
        reqs["requirements.txt"]:::app
    end

    subgraph "Data Layer"
        Models["speech/models.py"]:::data
        DB["Relational Database"]:::data
        Uploads["media/uploads/"]:::data
    end

    subgraph "External Services"
        FFMPEG["FFMPEG Binary"]:::external
        VOSKModel["VOSK Model Files"]:::external
    end

    Browser -->|HTTP Upload / UI| Views
    Views -->|Validate & Save| Forms
    Forms -->|Store File| Uploads
    Views -->|Invoke| Logic
    Logic -->|Transcode| FFMPEG
    Logic -->|Recognize| VOSKModel
    Logic -->|Save Transcript| Models
    Models -->|SQL| DB
    Views -->|Trigger WS| Consumers
    Consumers -->|WS Update| WSClient
    Browser -->|WS Connect| Consumers
    APIClient -->|JWT Auth / GET| Serializers
    Serializers -->|Query| DB
    APIClient -->|Receive JSON| APIClient

    click Views "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/views.py"
    click Forms "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/forms.py"
    click URLsHTTP "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/urls.py"
    click TemplatesUpload "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/templates/upload.html"
    click TemplatesList "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/templates/list.html"
    click Serializers "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/serializers.py"
    click URLsAPI "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/urls.py"
    click JWTConfig "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/myproject/settings.py"
    click Consumers "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/consumers.py"
    click RoutingWS "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/routing.py"
    click ASGI "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/myproject/asgi.py"
    click Logic "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/vosk_utils.py"
    click Models "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/speech/models.py"
    click Uploads "https://github.com/thanhphamtmu/django-vosk-autotranscriber/tree/main/media/uploads/"
    click manage "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/manage.py"
    click reqs "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/requirements.txt"
    click Settings "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/myproject/settings.py"
    click URLsProject "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/myproject/urls.py"
    click WSGI "https://github.com/thanhphamtmu/django-vosk-autotranscriber/blob/main/myproject/wsgi.py"
```
