# thevickypedia/pystream architecture

> Architecture diagram of the GitHub repository thevickypedia/pystream, 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/thevickypedia/pystream
- Repository: https://github.com/thevickypedia/pystream

## Overview

##### Project type and purpose
- PyStream is a self-hosted Python video‐streaming service built on FastAPI and Uvicorn.
- It exposes both REST endpoints and server‐side rendered HTML pages (via Jinja2 templates) to securely stream videos from a local folder.

##### File structure
- Top level contains CI/CD configs, documentation folders, `pyproject.toml`, and the `pystream/` package.
- Inside `pystream/`:
- main.py – the `start()` entrypoint that spins up Uvicorn & FastAPI
- logger.py – centralized logging setup
- utils.py – helpers (e.g., get_local_ip)
- models/ – core logic modules:
– config.py (env var loader)
– authenticator.py & secure.py (session & auth)
– stream.py & squire.py (range‐request video chunking)
– images.py (thumbnail generation)
– subtitles.py (subtitle serving)
- routers/ – FastAPI routers for auth, basic pages, and video endpoints
- templates/ – Jinja2 HTML for login, listing, streaming pages

##### README for additional insights
- Configurable via environment variables (AUTHORIZATION, VIDEO_SOURCE, optional SSL, CORS, etc.).
- Uses Uvicorn workers, FastAPI dependency injection, CORS middleware, thumbnails, secure cookies.

##### Detail
- Break out each router+model pairing rather than lumping under “API.”
- Explicitly show config loading & session cookie issuance.
- HTTP Range negotiation via Squire.
- Call out optional flows (AUTO_THUMBNAIL, SECURE_SESSION) with annotations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client and Gateway
    Client["Web Browser"]:::external
    SSL["SSL Termination"]:::external
    CDN["Optional CDN/CORS"]:::external

    %% Application Server Boundary
    subgraph "Application Server" 
        style ApplicationServer fill:#e0f7ff,stroke:#0288d1,stroke-width:2px
        ApplicationServer[(Uvicorn + FastAPI)]:::server

        %% Middleware Layer
        subgraph "Middleware" 
            CORS["CORS Middleware"]:::server
        end

        %% Routers Layer
        subgraph "Routers" 
            AuthRouter["AuthRouter"]:::server
            BasicRouter["BasicRouter"]:::server
            VideoRouter["VideoRouter"]:::server
        end

        %% Models Layer
        subgraph "Models" 
            ConfigLoader["ConfigLoader"]:::logic
            Authenticator["Authenticator"]:::logic
            SecureSession["SecureSession"]:::logic
            StreamEngine["StreamEngine"]:::logic
            Squire["Squire Range Handler"]:::logic
            ImageGenerator["ImageGenerator"]:::logic
            SubtitleHandler["SubtitleHandler"]:::logic
        end

        %% Template Engine
        Template["Jinja2 Template Engine"]:::server
    end

    %% Storage
    VIDEOFS[(VIDEO_SOURCE FS)]:::storage

    %% CI/CD and Docs
    CI["CI/CD Workflows"]:::external
    Docs["Documentation (Sphinx)"]:::external
    PreCommit["Pre-commit Hooks"]:::external
    PyProject["pyproject.toml"]:::external

    %% Flows
    Client -->|HTTPS Request| SSL
    SSL -->|Forward Request| ApplicationServer
    ApplicationServer --> CORS
    CORS --> ApplicationServer

    ApplicationServer -->|Routes to| AuthRouter
    ApplicationServer -->|Routes to| BasicRouter
    ApplicationServer -->|Routes to| VideoRouter

    AuthRouter -->|Depends on| Authenticator
    Authenticator -->|Uses| SecureSession
    SecureSession -->|Issues Cookie| ApplicationServer
    BasicRouter -->|Renders| Template
    Template -->|Loads Config| ConfigLoader
    VideoRouter -->|Streams via| StreamEngine
    StreamEngine -->|Range Requests| Squire
    StreamEngine -->|Reads Files| VIDEOFS
    Squire -->|Requests Chunks| VIDEOFS
    VideoRouter -->|Thumbnails| ImageGenerator
    ImageGenerator -->|Reads Files| VIDEOFS
    VideoRouter -->|Subtitles| SubtitleHandler
    SubtitleHandler -->|Reads Files| VIDEOFS

    ApplicationServer -->|Response| SSL
    SSL -->|HTTPS Response| Client

    %% Peripheral Modules
    CI --- Docs
    CI --- PreCommit
    CI --- PyProject

    %% Click Events
    click ApplicationServer "https://github.com/thevickypedia/pystream/blob/main/pystream/main.py"
    click CORS "https://github.com/thevickypedia/pystream/blob/main/pystream/utils.py"
    click ConfigLoader "https://github.com/thevickypedia/pystream/blob/main/pystream/models/config.py"
    click Authenticator "https://github.com/thevickypedia/pystream/blob/main/pystream/models/authenticator.py"
    click SecureSession "https://github.com/thevickypedia/pystream/blob/main/pystream/models/secure.py"
    click StreamEngine "https://github.com/thevickypedia/pystream/blob/main/pystream/models/stream.py"
    click Squire "https://github.com/thevickypedia/pystream/blob/main/pystream/models/squire.py"
    click ImageGenerator "https://github.com/thevickypedia/pystream/blob/main/pystream/models/images.py"
    click SubtitleHandler "https://github.com/thevickypedia/pystream/blob/main/pystream/models/subtitles.py"
    click AuthRouter "https://github.com/thevickypedia/pystream/blob/main/pystream/routers/auth.py"
    click BasicRouter "https://github.com/thevickypedia/pystream/blob/main/pystream/routers/basics.py"
    click VideoRouter "https://github.com/thevickypedia/pystream/blob/main/pystream/routers/video.py"
    click Template "https://github.com/thevickypedia/pystream/tree/main/pystream/templates/"
    click CI "https://github.com/thevickypedia/pystream/tree/main/ .github/workflows/"
    click Docs "https://github.com/thevickypedia/pystream/tree/main/docs/"
    click PreCommit "https://github.com/thevickypedia/pystream/blob/main/.pre-commit-config.yaml"
    click PyProject "https://github.com/thevickypedia/pystream/blob/main/pyproject.toml"

    %% Styles
    classDef server fill:#bbdefb,stroke:#1976d2,color:#0d47a1;
    classDef logic fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef storage fill:#fff9c4,stroke:#fbc02d,color:#f57f17,stroke-dasharray: 5 5;
    classDef external fill:#ffe0b2,stroke:#ef6c00,color:#e65100,stroke-dasharray: 2 2;
```
