# moontechlab/lunatv architecture

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

- Interactive diagram: https://gitdiagram.com/moontechlab/lunatv
- Repository: https://github.com/moontechlab/lunatv

## Overview

##### Project type and purpose
- MoonTV is a full-stack, server-rendered web application (Next.js 14 + App Router) that aggregates multiple video sources into a unified player/UI, provides a built-in admin panel (REST API under /src/app/api/admin/*), and persists user data (favorites, watch history) in Redis-style stores (Kvrocks/Redis/Upstash). It’s packaged as a Docker-ready monolith with PWA support.

##### File structure
- Top-level Docker + CI/CD: Dockerfile, .dockerignore, GitHub Actions workflow under .github/workflows/docker-image.yml
- Config & build: next.config.js, tsconfig.json, tailwind.config.ts, jest.config.js, lint/prettier configs
- App Router pages & API routes:
- /src/app/*.tsx (UI pages: home, search, detail, play, admin)
- /src/app/api/*/**/route.ts (REST endpoints for admin, auth, search, proxy, live, douban, etc.)
- Components: /src/components (reusable React components)
- Hooks: /src/hooks (e.g., useLongPress)
- Lib: /src/lib (db clients, auth, external-API wrappers, caching, utils)
- Middleware: src/middleware.ts (edge middleware for auth/redirects)

##### README for additional insights
- Tech stack: Next.js 14, Tailwind CSS, TypeScript, ArtPlayer, HLS.js
- Storage options: Kvrocks, Redis, Upstash (via env vars NEXT_PUBLIC_STORAGE_TYPE, KVROCKS_URL, REDIS_URL, UPSTASH_URL/TOKEN)
- Deployment: Docker Compose (core + Kvrocks/Redis), Zeabur one-click

a. Main components:
- Client (Browser/PWA)
- Next.js Server (Node.js container)
- Data stores (Kvrocks/Redis/Upstash)
- External APIs & services (Douban API or proxies, video/CDN endpoints)
b. Relationships & data flows:
1. Client → HTTP(S) → Next.js Server
‑ UI page requests (SSR/SSG) and API calls (/api/*)
2. Next.js Server ↔ Data store
‑ Reads/writes favorites, watch history, config cache
3. Next.js Server → External services
‑ Douban data fetch, site-provided VOD APIs, ad-skipping logic, image proxies, HLS segment proxy
4. Client ← HLS.js/ArtPlayer ← (via Next.js proxy or direct CDN) video streams
c. Architectural patterns / design principles:
- Monolithic Node.js container with layered structure: Presentation (React+Tailwind), Business Logic (API routes + lib services), Data Access (db clients), Integration adapters (external API wrappers)
- API routes as serverless-style functions inside Next.js
- PWA caching (service worker) for offline/installation
- Edge middleware for auth and routing
- Config driven by environment variables injected at container runtime
d. Key technologies/frameworks:
- Next.js 14 App Router & Server Actions
- React + Tailwind CSS
- Docker (core + Kvrocks/Redis containers)
- Redis-compatible stores (Kvrocks, Upstash)
- ArtPlayer & HLS.js for video playback
- Jest + ESLint + Prettier for code quality

##### Elements
- Clear labels on each component (e.g., “Next.js App Container”, “Kvrocks Store”, “Douban Proxy API”)
- Blue rectangles for UI/client
- Green for application/server
- Purple clouds for external services/CDN

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser/PWA)"
        direction TB
        SW["Service Worker & Manifest"]:::frontend
        SW -->|"generates manifest"| Layout
        click SW "https://github.com/moontechlab/lunatv/blob/main/scripts/generate-manifest.js"
        PW["proxy.worker.js"]:::frontend
        click PW "https://github.com/moontechlab/lunatv/blob/main/proxy.worker.js"
        Assets["Static Assets (public/)"]:::frontend
        click Assets "https://github.com/moontechlab/lunatv/tree/main/public/"
        Layout["Global Layout & Styles"]:::frontend
        click Layout "https://github.com/moontechlab/lunatv/blob/main/src/app/layout.tsx"
    end

    %% Presentation Layer
    subgraph "Presentation (UI Pages)"
        direction TB
        Home["Home Page"]:::frontend
        click Home "https://github.com/moontechlab/lunatv/blob/main/src/app/page.tsx"
        Search["Search Page"]:::frontend
        click Search "https://github.com/moontechlab/lunatv/blob/main/src/app/search/page.tsx"
        Detail["Detail Page"]:::frontend
        click Detail "https://github.com/moontechlab/lunatv/blob/main/src/app/detail/page.tsx"
        Play["Play Page"]:::frontend
        click Play "https://github.com/moontechlab/lunatv/blob/main/src/app/play/page.tsx"
        Warning["Warning Page"]:::frontend
        click Warning "https://github.com/moontechlab/lunatv/blob/main/src/app/warning/page.tsx"
        LivePage["Live Page"]:::frontend
        click LivePage "https://github.com/moontechlab/lunatv/blob/main/src/app/live/page.tsx"
        DoubanPage["Douban Page"]:::frontend
        click DoubanPage "https://github.com/moontechlab/lunatv/blob/main/src/app/douban/page.tsx"
        Login["Login Page"]:::frontend
        click Login "https://github.com/moontechlab/lunatv/blob/main/src/app/login/page.tsx"
        AdminUI["Admin Panel UI"]:::frontend
        click AdminUI "https://github.com/moontechlab/lunatv/blob/main/src/app/admin/page.tsx"
        Components["Components Library"]:::frontend
        click Components "https://github.com/moontechlab/lunatv/tree/main/src/components/"
        Hooks["Custom Hooks"]:::frontend
        click Hooks "https://github.com/moontechlab/lunatv/blob/main/src/hooks/useLongPress.ts"
    end

    %% Application Layer
    subgraph "Next.js App Container"
        direction TB
        SSR["Pages & SSR"]:::server
        API["API Routes"]:::server
        Middleware["Edge Middleware"]:::server
        click Middleware "https://github.com/moontechlab/lunatv/blob/main/src/middleware.ts"
        Lib["Business Logic & Adapters"]:::server
        click Lib "https://github.com/moontechlab/lunatv/tree/main/src/lib/"
        Config["Config & Build Files"]:::server
        click Config "https://github.com/moontechlab/lunatv/blob/main/next.config.js"
        Scripts["Utility Scripts"]:::server
        click Scripts "https://github.com/moontechlab/lunatv/blob/main/scripts/generate-manifest.js"
    end

    %% API Routes Breakdown
    subgraph "API Routes" 
        direction TB
        AdminAPI["Admin REST API"]:::server
        click AdminAPI "https://github.com/moontechlab/lunatv/tree/main/src/app/api/admin/"
        AuthAPI["Auth & User Endpoints"]:::server
        click AuthAPI "https://github.com/moontechlab/lunatv/blob/main/src/app/api/login/route.ts"
        SearchAPI["Search & History"]:::server
        click SearchAPI "https://github.com/moontechlab/lunatv/tree/main/src/app/api/search/"
        FavAPI["Favorites & Play Records"]:::server
        click FavAPI "https://github.com/moontechlab/lunatv/blob/main/src/app/api/favorites/route.ts"
        ProxyAPI["Proxy Endpoints"]:::server
        click ProxyAPI "https://github.com/moontechlab/lunatv/tree/main/src/app/api/proxy/"
        LiveAPI["Live Channel & EPG"]:::server
        click LiveAPI "https://github.com/moontechlab/lunatv/blob/main/src/app/api/live/channels/route.ts"
        DoubanAPI["Douban Integration"]:::server
        click DoubanAPI "https://github.com/moontechlab/lunatv/blob/main/src/app/api/douban/route.ts"
        MiscAPI["Misc (cron, config)"]:::server
        click MiscAPI "https://github.com/moontechlab/lunatv/blob/main/src/app/api/cron/route.ts"
    end

    %% Business Logic & Adapters
    subgraph "Business Logic & Adapters"
        direction TB
        DBClients["DB Clients & Adapters"]:::server
        click DBClients "https://github.com/moontechlab/lunatv/blob/main/src/lib/db.client.ts"
        AuthLib["Auth & Crypto"]:::server
        click AuthLib "https://github.com/moontechlab/lunatv/blob/main/src/lib/auth.ts"
        ExtAPI["External API Wrappers"]:::server
        click ExtAPI "https://github.com/moontechlab/lunatv/blob/main/src/lib/douban.client.ts"
        Utils["Caching & Utilities"]:::server
        click Utils "https://github.com/moontechlab/lunatv/blob/main/src/lib/utils.ts"
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Redis["Redis-compatible Store"]:::database
        click Redis "https://github.com/moontechlab/lunatv/blob/main/src/lib/redis.db.ts"
        KV["Kvrocks Store"]:::database
        click KV "https://github.com/moontechlab/lunatv/blob/main/src/lib/kvrocks.db.ts"
        Upstash["Upstash Store"]:::database
        click Upstash "https://github.com/moontechlab/lunatv/blob/main/src/lib/upstash.db.ts"
    end

    %% External Services
    subgraph "External Services"
        direction TB
        DoubanExt["Douban API"]:::external
        VOD["Video/CDN Endpoints"]:::external
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        GitHub["GitHub Actions"]:::ci
        click GitHub "https://github.com/moontechlab/lunatv/blob/main/.github/workflows/docker-image.yml"
        Dockerfile["Dockerfile"]:::ci
        click Dockerfile "https://github.com/moontechlab/lunatv/tree/main/Dockerfile"
        Vercel["Vercel & Zeabur"]:::ci
        click Vercel "https://github.com/moontechlab/lunatv/blob/main/vercel.json"
    end

    %% Connections
    Assets -->|serves assets| Home
    Home -->|renders via SSR| SSR
    Search -->|renders via SSR| SSR
    Detail -->|renders via SSR| SSR
    Play -->|renders via SSR| SSR
    LivePage -->|renders via SSR| SSR
    DoubanPage -->|renders via SSR| SSR
    AdminUI -->|renders via SSR| SSR
    Login -->|renders via SSR| SSR
    SSR -->|calls APIs| API
    API -->|invokes| AdminAPI
    API -->|invokes| AuthAPI
    API -->|invokes| SearchAPI
    API -->|invokes| FavAPI
    API -->|invokes| ProxyAPI
    API -->|invokes| LiveAPI
    API -->|invokes| DoubanAPI
    API -->|invokes| MiscAPI
    API -->|uses| DBClients
    API -->|uses| AuthLib
    API -->|uses| ExtAPI
    API -->|uses| Utils
    DBClients -->|reads/writes| Redis
    DBClients -->|reads/writes| KV
    DBClients -->|reads/writes| Upstash
    ExtAPI -->|fetches| DoubanExt
    SSR -->|streams video| VOD
    Client -->|plays via ArtPlayer/HLS.js| VOD
    GitHub -->|builds image| Dockerfile
    Dockerfile -->|deploys to| Vercel

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#000000
    classDef server fill:#e8f5e9,stroke:#1b5e20,color:#000000
    classDef database fill:#fff3e0,stroke:#e65100,color:#000000
    classDef external fill:#f3e5f5,stroke:#4a148c,color:#000000
    classDef ci fill:#fbe9e7,stroke:#bf360c,color:#000000
```
