# nstrmx/django-media-player architecture

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

- Interactive diagram: https://gitdiagram.com/nstrmx/django-media-player
- Repository: https://github.com/nstrmx/django-media-player

## Overview

##### Project Type and Purpose
- This is a full‐stack web application combining:
- A Django (Python) web server (MVC/MVT pattern) for the admin UI, metadata management, and serving HTML/CSS/JS.
- A Rust actix-based microservice as a dedicated media streaming backend.
- A browser side with a shared Web Worker to handle media streaming and playback.

##### File Structure
- Top Level:
- media_app/ — Django project (settings, URLs, WSGI/ASGI).
- media_app/media/ — Django “media” app: models (Media, Audio, Video, Radio), views, templates, static files (CSS/JS), admin customization, management commands.
- stream_backend/ — Rust Cargo project (main.rs, handlers.rs) running on port 8080.
- requirements.txt, Cargo.toml — Python and Rust dependencies.
- Key architectural patterns:
- Django MVT (Models → Views → Templates + static assets).
- Microservice style: separate HTTP streaming service in Rust.
- Shared Web Worker for cross‐tab communication and chunked streaming.

##### Extract Insights from README
- Two servers: Django on 127.0.0.1:8000 for UI/admin and static assets; Rust actix on 127.0.0.1:8080 for range‐based media streaming.
- Workflow: Admin adds media via Django management command → media files stored on disk + metadata in DB → user UI loads player page → Worker fetches media chunks from Rust service.

##### Main Components and Their Relationships
a. Browser / Frontend
- HTML templates and static JS/CSS served by Django.
- Shared Web Worker (worker.js) coordinates streaming across tabs.
- Player UI (player.html + player_handler.js).
b. Django Web App
- URL routing → views.py → templates / static.
- Admin interface for content management.
- Models ↔ Database (e.g., SQLite or Postgres).
- Management command add_media to scan FS and populate DB.
c. Media Storage
- File System (MEDIA_ROOT): raw audio/video files on disk.
d. Rust Actix Streaming Service
- HTTP range requests from Worker to `/stream/{media_id}`.
- Handlers read from FS and stream bytes.
e. Database
- Stores metadata: file paths, play counts, etc.

##### Architectural Patterns & Design Principles
- Separation of concerns: UI vs. metadata API vs. streaming.
- Microservice for heavy I/O (Rust) outside of Django process.
- Shared Web Worker for efficient resource usage (single stream for multiple tabs).
- Django MVT enforces clean layering of models, views, templates.

##### Essential Elements
- Clear labels: e.g., “Django App”, “Media DB”, “Media FS”, “Rust Streaming Service”, “Browser Web Worker”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser / Frontend
    subgraph "Browser / Frontend" 
        direction TB
        Browser["Browser"]:::frontend
        PlayerUI["Player UI\n(player.html + JS)"]:::frontend
        WebWorker["Shared Web Worker\n(worker.js)"]:::frontend
    end

    %% Django App Server
    subgraph "Django App Server\n(127.0.0.1:8000)" 
        direction TB
        DjangoServer["Django App\n(media_app/)"]:::backend
        subgraph "Core Settings & Entry" 
            direction TB
            Settings["settings.py"]:::backend
            URLsCore["urls.py"]:::backend
            WSGI["wsgi.py"]:::backend
            ASGI["asgi.py"]:::backend
            Manage["manage.py"]:::backend
        end
        subgraph "Models & DB Schema" 
            direction TB
            Models["models.py"]:::backend
            Migrations["migrations/"]:::backend
        end
        subgraph "Views & Routing" 
            direction TB
            Views["views.py"]:::backend
            URLsApp["urls.py"]:::backend
        end
        subgraph "Admin & Commands" 
            direction TB
            Admin["admin.py"]:::backend
            AddMedia["add_media.py"]:::backend
        end
        subgraph "Templates" 
            direction TB
            TemplatesPlayer["player.html"]:::frontend
            TemplatesAdmin["admin templates"]:::frontend
        end
        subgraph "Static Assets" 
            direction TB
            CSS["player.css"]:::frontend
            JSHandler["player_handler.js"]:::frontend
            JSBase["player_base.js"]:::frontend
            HostHandler["host_handler.js"]:::frontend
            CommonJS["common.js"]:::frontend
            WorkerJS["worker.js"]:::frontend
        end
        Requirements["requirements.txt"]:::backend
    end

    %% Rust Service
    subgraph "Rust Actix Streaming Service\n(127.0.0.1:8080)" 
        direction TB
        RustService["stream_backend/"]:::backend
        MainRS["main.rs"]:::backend
        Handlers["handlers.rs"]:::backend
        CargoT["Cargo.toml"]:::backend
        CargoL["Cargo.lock"]:::backend
    end

    %% Storage & Database
    Database["Database\n(SQLite/Postgres)"]:::storage_db
    FileSystem["File System Storage\n(MEDIA_ROOT)"]:::storage_fs

    %% Connections
    Browser -->|"GET HTML/CSS/JS,\nAPI calls"| DjangoServer
    PlayerUI -->|"load templates & JS"| DjangoServer
    WebWorker -->|"Range GET /stream/{id}"| RustService
    DjangoServer -->|"ORM queries"| Database
    DjangoServer -->|"scan & serve media files"| FileSystem
    RustService -->|"read chunks from FS"| FileSystem

    %% Click Events for component mapping
    click Settings "https://github.com/nstrmx/django-media-player/blob/master/media_app/media_app/settings.py"
    click URLsCore "https://github.com/nstrmx/django-media-player/blob/master/media_app/media_app/urls.py"
    click WSGI "https://github.com/nstrmx/django-media-player/blob/master/media_app/media_app/wsgi.py"
    click ASGI "https://github.com/nstrmx/django-media-player/blob/master/media_app/media_app/asgi.py"
    click Manage "https://github.com/nstrmx/django-media-player/blob/master/media_app/manage.py"
    click Models "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/models.py"
    click Migrations "https://github.com/nstrmx/django-media-player/tree/master/media_app/media/migrations/"
    click Views "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/views.py"
    click URLsApp "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/urls.py"
    click Admin "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/admin.py"
    click AddMedia "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/management/commands/add_media.py"
    click TemplatesPlayer "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/templates/media/player.html"
    click TemplatesAdmin "https://github.com/nstrmx/django-media-player/tree/master/media_app/media/templates/media/admin/"
    click CSS "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/static/media/css/player.css"
    click JSHandler "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/static/media/js/player_handler.js"
    click JSBase "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/static/media/js/player_base.js"
    click HostHandler "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/static/media/js/host_handler.js"
    click CommonJS "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/static/media/js/common.js"
    click WorkerJS "https://github.com/nstrmx/django-media-player/blob/master/media_app/media/static/media/js/worker.js"
    click Requirements "https://github.com/nstrmx/django-media-player/blob/master/media_app/requirements.txt"
    click MainRS "https://github.com/nstrmx/django-media-player/blob/master/stream_backend/src/main.rs"
    click Handlers "https://github.com/nstrmx/django-media-player/blob/master/stream_backend/src/handlers.rs"
    click CargoT "https://github.com/nstrmx/django-media-player/blob/master/stream_backend/Cargo.toml"
    click CargoL "https://github.com/nstrmx/django-media-player/blob/master/stream_backend/Cargo.lock"

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#2d8,stroke-width:1px
    classDef backend fill:#e0f0ff,stroke:#28f,stroke-width:1px
    classDef storage_db fill:#ffe0b3,stroke:#fa0,stroke-width:1px
    classDef storage_fs fill:#f0f0f0,stroke:#888,stroke-width:1px
```
