# aljanjic/unlock-videos-app architecture

> Architecture diagram of the GitHub repository aljanjic/unlock-videos-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aljanjic/unlock-videos-app
- Repository: https://github.com/aljanjic/unlock-videos-app

## Overview

##### Project type and purpose
- This is a full-stack Django web application (“UnlockVideosApp”) whose primary function is:
- Receiving user-uploaded audio/video
- Running Whisper AI locally to generate transcripts
- Persisting transcripts in PostgreSQL
- Allowing users to summarize transcripts via the OpenAI gpt-3.5-turbo API

##### File structure
- Top-level files:
- Dockerfile & docker-compose.yml → containerized deployment
- requirements.txt → Python dependencies (Django, Whisper, OpenAI SDK, psycopg2, Gunicorn, etc.)
- .gitignore
- unlock_videos_app/conf: Gunicorn config
- unlock_videos_app/unlock_videos_app: Django project module (settings, URLs, WSGI/ASGI)
- unlock_videos_app/transcription: Django app
- models.py → Transcript, TranscriptDetail, UploadedFile, UploadedImage
- serializers.py → DRF serializers (if any)
- views.py, forms.py, templates → MVC (views + HTML UI)
- migrations → evolving schema
- urls.py → transcription routes

##### README for technical stack
- Django framework (MVC)
- PostgreSQL database
- Whisper AI model (local inference)
- OpenAI GPT-3.5-turbo (external API)
- Gunicorn + Docker for production

##### Main components
a. Client (Web Browser)
– Interacts via HTTP(S)
– Renders HTML templates and forms
b. Django Web Server
– Gunicorn WSGI worker
– Django URL router → views → templates / serializers
c. Media Storage
– Local filesystem or mounted volume (for uploaded media)
d. Whisper Transcription Service
– Python module (in‐process) invoking Whisper AI
– Accepts media file path → outputs text
e. Transcript Database
– PostgreSQL
– Tables for UploadedFile, Transcript, TranscriptDetail, UploadedImage
f. GPT Summarization Service
– HTTP client to OpenAI API
– Accepts transcript text → returns summary
g. Optional Reverse Proxy (e.g., Nginx)
– SSL termination
– Static file serving
– Proxy to Gunicorn

##### Relationships and interactions
1. User uploads file via frontend form → Django View
2. Django View saves file to Media Storage & creates UploadedFile record in DB
3. Django invokes Whisper Transcription Service → generates transcript text
4. Transcript is saved to PostgreSQL (Transcript + TranscriptDetail)
5. User clicks “Summarize” → Django View calls GPT Summarization Service (OpenAI API)
6. Summary is persisted to DB and rendered back to the user

##### Architectural patterns & design principles
- MVC (Django) separating models, views, templates
- Service layer for AI operations (Whisper + GPT calls)
- Containerization (Docker, docker-compose) for environment consistency
- Configuration (gunicorn_config.py) externalized from code

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Web Browser"]:::frontend
    Client -->|"HTTP/HTTPS"| Nginx["Nginx Reverse Proxy"]:::backend

    %% Application Layer
    Nginx -->|"Proxy to Gunicorn"| Gunicorn["Gunicorn WSGI Server"]:::backend
    subgraph "Django Application"
        direction TB
        Manage["manage.py"]:::config
        Settings["settings.py"]:::config
        URLs["urls.py"]:::config
        WSGI["wsgi.py"]:::config
        ASGI["asgi.py"]:::config

        subgraph "Transcription App (MVC)"
            direction TB
            Models["models.py"]:::data
            Migrations["migrations/"]:::data
            Forms["forms.py"]:::frontend
            TemplatesUpload["upload_media.html"]:::frontend
            TemplatesAdd["add_transcript.html"]:::frontend
            TemplatesView["view_transcripts.html"]:::frontend
            Views["views.py"]:::backend
            Serializers["serializers.py"]:::backend
            AppURLs["urls.py"]:::backend
        end

        Gunicorn -->|loads| Manage
        Gunicorn -->|imports| Settings
        Gunicorn -->|routes| URLs
        Gunicorn -->|serves| Views
    end

    %% Media Storage
    Gunicorn -->|"Save Media"| MediaStorage["Media Storage Volume"]:::data

    %% Whisper Service
    Gunicorn -->|"Invoke Local Whisper"| Whisper["Whisper Transcription Service"]:::backend
    Whisper -->|"Output Transcript"| TranscriptDB

    %% Database
    subgraph "PostgreSQL Database"
        direction TB
        TranscriptDB["Transcripts Tables"]:::data
    end
    Gunicorn -->|"Read/Write Models"| TranscriptDB

    %% GPT Summarization
    Gunicorn -->|"Call OpenAI GPT-3.5-turbo"| OpenAIGPT["OpenAI GPT Service"]:::external
    OpenAIGPT -->|"Return Summary"| TranscriptDB

    %% Responses
    Gunicorn -->|"Render Templates / JSON"| Client

    %% Click Events
    click Dockerfile "https://github.com/aljanjic/unlock-videos-app/tree/main/Dockerfile"
    click DockerCompose "https://github.com/aljanjic/unlock-videos-app/blob/main/docker-compose.yml"
    click Manage "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/manage.py"
    click Settings "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/unlock_videos_app/settings.py"
    click URLs "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/unlock_videos_app/urls.py"
    click WSGI "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/unlock_videos_app/wsgi.py"
    click ASGI "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/unlock_videos_app/asgi.py"
    click Gunicorn "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/conf/gunicorn_config.py"
    click Models "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/models.py"
    click Migrations "https://github.com/aljanjic/unlock-videos-app/tree/main/unlock_videos_app/transcription/migrations/"
    click Forms "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/forms.py"
    click TemplatesUpload "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/templates/upload_media.html"
    click TemplatesAdd "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/templates/add_transcript.html"
    click TemplatesView "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/templates/view_transcripts.html"
    click Views "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/views.py"
    click Serializers "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/serializers.py"
    click AppURLs "https://github.com/aljanjic/unlock-videos-app/blob/main/unlock_videos_app/transcription/urls.py"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef data fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00;
    classDef external fill:#FFE0E0,stroke:#d73a49,color:#d73a49;
    classDef config fill:#F0F0F0,stroke:#666666,color:#333333;
```
