# senshinya/moontv architecture

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

- Interactive diagram: https://gitdiagram.com/senshinya/moontv
- Repository: https://github.com/senshinya/moontv

## Overview

##### Main Components
a. Client (Browser / PWA)
b. Next.js Application Server
- App Router (React pages under src/app)
- API Routes (serverless functions under src/app/api)
- Middleware (src/middleware.ts)
c. Data Stores (pluggable)
- LocalStorage (client-side)
- Redis (native or Upstash)
- Cloudflare D1
d. External Services
- Third-party video/content APIs (as configured in config.json)
- Douban API (via lib/douban.client.ts)
e. Proxy Worker (proxy.worker.js) for image or cross-origin requests
f. CI/CD & Deployment
- GitHub Actions → Docker image / Vercel / Cloudflare Pages

##### Interactions & Data Flows
a. Browser → Next.js SSR pages (renders React + Tailwind CSS)
b. Browser → Next.js API endpoints (fetch JSON for search, detail, playrecords, auth, image-proxy, admin)
c. API endpoints → Data Store (read/write play records, favorites, user credentials)
d. API endpoints → External Content APIs & Douban API → transform & cache (lib/*)
e. Proxy Worker → browser for images (bypass CORS)
f. CI/CD triggers → build & deploy container or serverless

##### Architectural Patterns & Principles
- Monolithic BFF (Backend-for-Frontend): UI pages and JSON API co-located
- App Router (Next.js 14) differentiates server vs. client components
- Serverless-style API routes, each in its own folder under src/app/api
- Pluggable storage layer (LocalStorage / Redis / D1 / Upstash), selected via NEXT_PUBLIC_STORAGE_TYPE
- PWA offline cache & asset serving from public/ + service worker
- Configuration-driven aggregation (config.json drives source APIs)

##### Relevant Technologies & Libraries
- Next.js 14 (App Router + Middleware)
- Tailwind CSS 3, TypeScript 4
- ArtPlayer & HLS.js (client-side video player)
- Redis / Upstash SDK (lib/redis.db.ts, lib/upstash.db.ts)
- Cloudflare D1 adapter (lib/d1.db.ts)
- Axios/fetch wrappers (lib/downstream.ts, lib/douban.client.ts)
- CI/CD: GitHub Actions (.github/workflows), Dockerfile, vercel.json

##### Details to Capture
- The “App Router” vs. “API Routes” separation inside the Next.js server.
- The pluggable storage strategy (local vs. server DB) and environment-variable switch.
- The external-API aggregation layer (lib/downstream.ts & config.json).
- Proxy Worker’s role in image-proxy requests.
- CI/CD pipelines (.github/workflows/docker-image.yml for Docker, sync.yml for fork sync).
- Admin panel (/admin) as part of the API & rendering sub-layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser / PWA"]:::frontend
        UI["UI Pages (Search, Play, Favorites, Admin)"]:::frontend
        SW["Service Worker"]:::frontend
        Assets["Public (static assets)"]:::frontend
        Browser -->|"renders UI"| UI
        Browser -->|"fetch via SW"| SW
        SW -->|"caches assets"| Assets
    end

    %% Server Layer
    subgraph "Next.js Server" 
        direction TB
        Rendering["Rendering Layer\n(App Router)"]:::backend
        APILayer["API Routes\n(src/app/api)"]:::backend
        Middleware["Middleware"]:::backend
        Rendering -->|"SSR / SSG"| Browser
        Browser -->|"HTTP GET /page"| Rendering
        Browser -->|"HTTP GET /api/*"| APILayer
        Browser -->|"passes through"| Middleware
    end

    %% Storage Layer
    subgraph "Storage Layer"
        direction TB
        LocalStorage["LocalStorage (client-side)"]:::datastore
        Redis["Redis Adapter"]:::datastore
        Upstash["Upstash Adapter"]:::datastore
        D1["Cloudflare D1 Adapter"]:::datastore
        APILayer -->|"read/write"| Redis
        APILayer -->|"read/write"| Upstash
        APILayer -->|"read/write"| D1
        UI -->|"local cache"| LocalStorage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Config["Configuration Driver\n(config.json)"]:::external
        VideoAPIs["Video Source APIs"]:::external
        Aggregator["API Aggregator\n(lib/downstream.ts)"]:::external
        Douban["Douban API Client"]:::external
        ProxyWorker["Proxy Worker"]:::external
        APILayer -->|"fetch content"| Aggregator
        APILayer -->|"fetch details"| Douban
        Aggregator -->|"uses config"| Config
        Browser -->|"image proxy"| ProxyWorker
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        GH_Docker["GitHub Actions\n(docker-image.yml)"]:::cicd
        GH_Sync["GitHub Actions\n(sync.yml)"]:::cicd
        DockerfileNode["Dockerfile"]:::cicd
        DockerIgnore[".dockerignore"]:::cicd
        Vercel["Vercel Config\n(vercel.json)"]:::cicd
        Scripts["Build & Utility Scripts"]:::cicd
        GH_Docker --> DockerfileNode
        GH_Docker --> DockerIgnore
        GH_Sync --> Scripts
        DockerfileNode --> Vercel
    end

    %% Configuration dashed flows
    Config -.->|"drives"| Aggregator

    %% Click Events
    click UI "https://github.com/senshinya/moontv/tree/main/src/app"
    click SW "https://github.com/senshinya/moontv/blob/main/proxy.worker.js"
    click Assets "https://github.com/senshinya/moontv/tree/main/public/"
    click Rendering "https://github.com/senshinya/moontv/blob/main/src/app/layout.tsx"
    click APILayer "https://github.com/senshinya/moontv/tree/main/src/app/api"
    click Middleware "https://github.com/senshinya/moontv/blob/main/src/middleware.ts"
    click Config "https://github.com/senshinya/moontv/blob/main/config.json"
    click Aggregator "https://github.com/senshinya/moontv/blob/main/src/lib/downstream.ts"
    click Douban "https://github.com/senshinya/moontv/blob/main/src/lib/douban.client.ts"
    click Redis "https://github.com/senshinya/moontv/blob/main/src/lib/redis.db.ts"
    click Upstash "https://github.com/senshinya/moontv/blob/main/src/lib/upstash.db.ts"
    click D1 "https://github.com/senshinya/moontv/blob/main/src/lib/d1.db.ts"
    click GH_Docker "https://github.com/senshinya/moontv/blob/main/.github/workflows/docker-image.yml"
    click GH_Sync "https://github.com/senshinya/moontv/blob/main/.github/workflows/sync.yml"
    click DockerfileNode "https://github.com/senshinya/moontv/tree/main/Dockerfile"
    click DockerIgnore "https://github.com/senshinya/moontv/blob/main/.dockerignore"
    click Vercel "https://github.com/senshinya/moontv/blob/main/vercel.json"
    click Scripts "https://github.com/senshinya/moontv/blob/main/scripts/convert-config.js"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef datastore fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#455A64
    classDef cicd fill:#F3E5F5,stroke:#8E24AA,color:#4A148C
```
