# ctzzg/libretv architecture

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

- Interactive diagram: https://gitdiagram.com/ctzzg/libretv
- Repository: https://github.com/ctzzg/libretv

## Overview

##### Project type and purpose
- LibreTV is a full-stack, serverless‐style web application that delivers a lightweight, password‐protected video search and playback platform.
- It combines a static front end (HTML/CSS/JS, PWA, service worker) with backend proxy functionality implemented as serverless functions (Netlify, Vercel, Cloudflare) and a standalone Node.js server for local/docker development.

##### File structure
- Top‐level assets:
- index.html, player.html, watch.html, about.html, privacy.html – static entry points
- css/, js/ – frontend resources (styles, UI logic, video player integration)
- service-worker.js, manifest.json – PWA support
- image/ – branding assets
- Backend / serverless:
- api/proxy/[...path].mjs & functions/proxy/[[path]].js & netlify/functions/proxy.mjs – unified API proxy endpoints
- server.mjs & middleware.js – Express‐style server for local and Docker use
- proxy.lua & nginx.conf – optional Nginx-based proxy for Docker/Nginx deployments
- Deployment/config:
- Dockerfile, docker-compose.yml, docker-entrypoint.sh – containerized deployment
- netlify.toml, vercel.json – serverless hosting config
- .github/workflows/*.yml – CI/CD for versioning, Docker builds, syncing
- .env.example – environment variable template (PASSWORD, PORT)

##### README for additional insights
- Describes architecture as “static front end + serverless proxy” supporting Apple CMS V10 API
- Emphasizes password protection via `PASSWORD` env var
- Lists deployment targets: Cloudflare Pages, Vercel, Netlify, Docker

a. Main components:
1. Client Browser
- Loads static assets from CDN/hosting (HTML, CSS, JS)
- Registers Service Worker / PWA
- Renders UI, interacts via JS (api.js, player.js, watch.js)
2. Static Asset Hosting
- Vercel/Netlify/Cloudflare Pages or Docker/nginx static server
3. Proxy Backend
- Serverless Functions (api/proxy, functions/proxy, netlify/functions)
- Local Node.js server (server.mjs + middleware.js)
- Optional Nginx + Lua proxy
4. External Video Content APIs
- Third‐party “Apple CMS” V10 endpoints for search & detail
- HLS video streaming URLs
5. Data Stores / LocalStorage
- Browser localStorage for settings, version checks, password

b. Relationships and interactions:
- Browser → Static Host: GET HTML/CSS/JS/manifest
- Browser → Service Worker (intercepts, caches)
- JS in Browser → Proxy Backend: AJAX calls to `/api/proxy/...`
- Proxy Backend → External APIs/HLS Sources: fetch & rewrite
- Proxy Backend → Browser: proxied JSON, M3U8 playlists, media segments
- Browser → LocalStorage: read/write settings & PASSWORD

c. Architectural patterns & principles:
- “Jamstack” style: prebuilt static + serverless functions
- PWA + Service Worker caching for offline/resume
- API Gateway pattern: single proxy entrypoint abstracts CORS & API versions
- Deployment‐agnostic: adapters for Netlify/Vercel/Cloudflare Functions or Docker/Express

d. Key technologies:
- Frontend: HTML5, CSS3 (Tailwind in build pipeline), ES6+ JS, DPlayer, HLS.js
- Backend: Node.js (server.mjs), Express‐like middleware, serverless function runtimes
- Proxy: Lua (optional), Netlify/Vercel/Cloudflare Function APIs
- Deployment: Docker, docker-compose, GitHub Actions

##### Detail
- Serverless endpoint path (`/api/proxy/[...path]`, `/proxy.mjs`)
- Branching for Netlify vs. Vercel vs. Cloudflare vs. Docker flows
- Password‐check middleware in your proxy block
- HLS stream rewriting logic, Service Worker cache strategy, and PWA manifest

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser Layer
    subgraph "Client Browser" 
        direction TB
        IndexHTML["index.html"]:::frontend
        PlayerHTML["player.html"]:::frontend
        WatchHTML["watch.html"]:::frontend
        AboutHTML["about.html"]:::frontend
        PrivacyHTML["privacy.html"]:::frontend

        CSSIndex["css/index.css"]:::frontend
        CSSModals["css/modals.css"]:::frontend
        CSSPlayer["css/player.css"]:::frontend
        CSSStyles["css/styles.css"]:::frontend
        CSSWatch["css/watch.css"]:::frontend

        JSAPI["js/api.js"]:::frontend
        JSApp["js/app.js"]:::frontend
        JSConfig["js/config.js"]:::frontend
        JSDouban["js/douban.js"]:::frontend
        JSIndexPage["js/index-page.js"]:::frontend
        JSPassword["js/password.js"]:::frontend
        JSPlayer["js/player.js"]:::frontend
        JSPWARegister["js/pwa-register.js"]:::frontend
        JSSha256["js/sha256.js"]:::frontend
        JSUI["js/ui.js"]:::frontend
        JSVersionCheck["js/version-check.js"]:::frontend
        JSWakelock["js/wakelock.js"]:::frontend
        JSWatch["js/watch.js"]:::frontend

        ServiceWorker["service-worker.js"]:::frontend
        Manifest["manifest.json"]:::frontend

        BrandingAsset["image/nomedia.psd"]:::frontend
        LocalStorage[("LocalStorage")]:::frontend
    end

    %% Static Hosting Layer
    subgraph "Static Asset Hosting" 
        direction TB
        CDN["CDN / Static Server"]:::deployment
    end

    %% Proxy Backend Layer
    subgraph "Proxy Backend" 
        direction TB
        subgraph "Serverless Functions" 
            direction TB
            APIMJS["api/proxy/[...path].mjs"]:::backend
            FuncJS["functions/proxy/[[path]].js"]:::backend
            NetlifyMJS["netlify/functions/proxy.mjs"]:::backend
        end
        subgraph "Node.js Server (Local/Docker)" 
            direction TB
            ServerMJS["server.mjs"]:::backend
            MiddlewareJS["middleware.js"]:::backend
        end
        subgraph "Nginx + Lua (Optional)" 
            direction TB
            NginxConf["nginx.conf"]:::backend
            ProxyLua["proxy.lua"]:::backend
        end
    end

    %% External Services
    subgraph "External Video Content APIs" 
        direction TB
        AppleCMS["Apple CMS V10 API"]:::external
        HLSStreams["HLS Video Streaming"]:::external
    end

    %% Deployment & Configuration
    subgraph "Deployment & Configuration" 
        direction TB
        Dockerfile["Dockerfile"]:::deployment
        DockerCompose["docker-compose.yml"]:::deployment
        DockerEntrypoint["docker-entrypoint.sh"]:::deployment

        NetlifyConfig["netlify.toml"]:::deployment
        VercelConfig["vercel.json"]:::deployment

        EnvExample[".env.example"]:::deployment
        CI_DockerBuild[".github/workflows/docker-build.yml"]:::deployment
        CI_Sync[".github/workflows/sync.yml"]:::deployment
        CI_Version[".github/workflows/version.yml"]:::deployment
    end

    %% Relationships
    IndexHTML -->|GET assets| CDN
    PlayerHTML -->|GET assets| CDN
    WatchHTML -->|GET assets| CDN
    AboutHTML -->|GET assets| CDN
    PrivacyHTML -->|GET assets| CDN

    CSSIndex --> CDN
    CSSModals --> CDN
    CSSPlayer --> CDN
    CSSStyles --> CDN
    CSSWatch --> CDN

    JSAPI --> CDN
    JSApp --> CDN
    JSConfig --> CDN
    JSDouban --> CDN
    JSIndexPage --> CDN
    JSPassword --> CDN
    JSPlayer --> CDN
    JSPWARegister --> CDN
    JSSha256 --> CDN
    JSUI --> CDN
    JSVersionCheck --> CDN
    JSWakelock --> CDN
    JSWatch --> CDN

    IndexHTML -->|register| ServiceWorker
    ServiceWorker -->|cache| CDN

    JSAPI -->|AJAX /api/proxy| APIMJS
    JSApp -->|AJAX /api/proxy| APIMJS
    JSConfig -->|AJAX /api/proxy| APIMJS

    APIMJS -->|fetch & rewrite| AppleCMS
    APIMJS -->|stream proxy| HLSStreams

    FuncJS -->|fetch & rewrite| AppleCMS
    NetlifyMJS -->|fetch & rewrite| AppleCMS

    ServerMJS -->|middleware proxy| AppleCMS
    ServerMJS -->|middleware proxy| HLSStreams
    MiddlewareJS -->|password check| ServerMJS

    NginxConf -->|proxy| AppleCMS
    ProxyLua -->|rewrite| HLSStreams

    JSAPI -->|read/write| LocalStorage
    JSPassword -->|read/write| LocalStorage
    JSVersionCheck -->|read/write| LocalStorage

    %% Deployment arrows
    Dockerfile --> ServerMJS
    DockerCompose --> Dockerfile
    DockerEntrypoint --> DockerCompose

    NetlifyConfig --> APIMJS
    VercelConfig --> FuncJS

    EnvExample -->|defines PASSWORD| APIMJS
    EnvExample -->|defines PASSWORD| FuncJS
    EnvExample -->|defines PASSWORD| ServerMJS

    CI_DockerBuild --> Dockerfile
    CI_Sync -->|sync static| CDN
    CI_Version -->|version bump| CDN

    %% Click Events
    click IndexHTML "https://github.com/ctzzg/libretv/blob/main/index.html"
    click PlayerHTML "https://github.com/ctzzg/libretv/blob/main/player.html"
    click WatchHTML "https://github.com/ctzzg/libretv/blob/main/watch.html"
    click AboutHTML "https://github.com/ctzzg/libretv/blob/main/about.html"
    click PrivacyHTML "https://github.com/ctzzg/libretv/blob/main/privacy.html"

    click CSSIndex "https://github.com/ctzzg/libretv/blob/main/css/index.css"
    click CSSModals "https://github.com/ctzzg/libretv/blob/main/css/modals.css"
    click CSSPlayer "https://github.com/ctzzg/libretv/blob/main/css/player.css"
    click CSSStyles "https://github.com/ctzzg/libretv/blob/main/css/styles.css"
    click CSSWatch "https://github.com/ctzzg/libretv/blob/main/css/watch.css"

    click JSAPI "https://github.com/ctzzg/libretv/blob/main/js/api.js"
    click JSApp "https://github.com/ctzzg/libretv/blob/main/js/app.js"
    click JSConfig "https://github.com/ctzzg/libretv/blob/main/js/config.js"
    click JSDouban "https://github.com/ctzzg/libretv/blob/main/js/douban.js"
    click JSIndexPage "https://github.com/ctzzg/libretv/blob/main/js/index-page.js"
    click JSPassword "https://github.com/ctzzg/libretv/blob/main/js/password.js"
    click JSPlayer "https://github.com/ctzzg/libretv/blob/main/js/player.js"
    click JSPWARegister "https://github.com/ctzzg/libretv/blob/main/js/pwa-register.js"
    click JSSha256 "https://github.com/ctzzg/libretv/blob/main/js/sha256.js"
    click JSUI "https://github.com/ctzzg/libretv/blob/main/js/ui.js"
    click JSVersionCheck "https://github.com/ctzzg/libretv/blob/main/js/version-check.js"
    click JSWakelock "https://github.com/ctzzg/libretv/blob/main/js/wakelock.js"
    click JSWatch "https://github.com/ctzzg/libretv/blob/main/js/watch.js"

    click ServiceWorker "https://github.com/ctzzg/libretv/blob/main/service-worker.js"
    click Manifest "https://github.com/ctzzg/libretv/blob/main/manifest.json"
    click BrandingAsset "https://github.com/ctzzg/libretv/blob/main/image/nomedia.psd"

    click APIMJS "https://github.com/ctzzg/libretv/blob/main/api/proxy/[...path].mjs"
    click FuncJS "https://github.com/ctzzg/libretv/blob/main/functions/proxy/[[path]].js"
    click NetlifyMJS "https://github.com/ctzzg/libretv/blob/main/netlify/functions/proxy.mjs"
    click ServerMJS "https://github.com/ctzzg/libretv/blob/main/server.mjs"
    click MiddlewareJS "https://github.com/ctzzg/libretv/blob/main/middleware.js"
    click NginxConf "https://github.com/ctzzg/libretv/blob/main/nginx.conf"
    click ProxyLua "https://github.com/ctzzg/libretv/blob/main/proxy.lua"

    click Dockerfile "https://github.com/ctzzg/libretv/tree/main/Dockerfile"
    click DockerCompose "https://github.com/ctzzg/libretv/blob/main/docker-compose.yml"
    click DockerEntrypoint "https://github.com/ctzzg/libretv/blob/main/docker-entrypoint.sh"
    click NetlifyConfig "https://github.com/ctzzg/libretv/blob/main/netlify.toml"
    click VercelConfig "https://github.com/ctzzg/libretv/blob/main/vercel.json"
    click EnvExample "https://github.com/ctzzg/libretv/blob/main/.env.example"
    click CI_DockerBuild "https://github.com/ctzzg/libretv/blob/main/.github/workflows/docker-build.yml"
    click CI_Sync "https://github.com/ctzzg/libretv/blob/main/.github/workflows/sync.yml"
    click CI_Version "https://github.com/ctzzg/libretv/blob/main/.github/workflows/version.yml"

    %% Styles
    classDef frontend fill:#e0ffe0,stroke:#006600,stroke-width:1px
    classDef backend fill:#e0f0ff,stroke:#004080,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#999999,stroke-width:1px
    classDef deployment fill:#fff4e6,stroke:#cc6600,stroke-width:1px
```
