# tud8951/moontvplus architecture

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

- Interactive diagram: https://gitdiagram.com/tud8951/moontvplus
- Repository: https://github.com/tud8951/moontvplus

## Overview

MoonTVPlus is a configurable, multi-source streaming and media hub. Users search configured providers, inspect titles and episodes, then play streams; accounts, preferences, and viewing state are persisted. Other documented product branches include private libraries, live TV, music, danmaku, Douban discovery and comments, offline downloads, and synchronized watch rooms. The graph reflects sampled route-to-library calls and README-described capabilities; several feature implementations were not sampled, so their internal links are omitted.

Main entry points: [`src/app/api/source-detail/route.ts`](https://github.com/tud8951/moontvplus/blob/main/src/app/api/source-detail/route.ts) (Source detail lookup), [`src/lib/config.ts`](https://github.com/tud8951/moontvplus/blob/main/src/lib/config.ts) (Application config), [`src/lib/downstream.ts`](https://github.com/tud8951/moontvplus/blob/main/src/lib/downstream.ts) (Provider search), [`src/app/api/search/route.ts`](https://github.com/tud8951/moontvplus/blob/main/src/app/api/search/route.ts) (Aggregated search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Discovery and playback"]
  node_search_ui["Search experience<br/>[page.tsx]"]
  node_search_api["Aggregated search<br/>[route.ts]"]
  node_downstream["Provider search<br/>[downstream.ts]"]
  node_detail_api["Title details<br/>[route.ts]"]
  node_source_detail["Source detail lookup<br/>[route.ts]"]
  node_player["Video player<br/>[page.tsx]"]
  node_danmaku["Danmaku<br/>[api.ts]"]
end

subgraph group_services["Media integrations"]
  node_douban["Douban discovery<br/>[douban.client.ts]"]
  node_tmdb_search["TMDB search<br/>[tmdb.search.ts]"]
  node_emby_manager["Emby integration<br/>[emby-manager.ts]"]
  node_openlist_client["OpenList client<br/>[openlist.client.ts]"]
  node_video_parser["Video parsing<br/>[video-parser.ts]"]
  node_live["Live TV<br/>[page.tsx]"]
  node_music["Music library<br/>[page.tsx]"]
  node_offline["Offline downloads"]
end

subgraph group_accounts["Accounts and state"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_refresh["Token refresh<br/>[refresh-token.ts]"]
  node_db["Storage facade<br/>[db.ts]"]
  node_db_client["Browser state<br/>[db.client.ts]"]
  node_d1[("D1 storage<br/>[d1.db.ts]")]
  node_postgres[("Postgres storage<br/>[postgres.db.ts]")]
end

subgraph group_community["Social viewing"]
  node_watch_ui["Watch room UI"]
  node_watch_socket["Room socket server"]
  node_watch_types["Room event types<br/>[watch-room.ts]"]
end

subgraph group_operations["Administration"]
  node_config["Application config<br/>[config.ts]"]
  node_admin["Admin configuration<br/>[page.tsx]"]
end

node_viewer(("Viewer"))

node_viewer -->|"searches"| node_search_ui
node_search_ui -.->|"queries"| node_search_api
node_search_api -->|"loads sources"| node_config
node_search_api -->|"searches providers"| node_downstream
node_downstream -->|"reads settings"| node_config
node_viewer -.->|"opens title"| node_detail_api
node_detail_api -->|"fetches details"| node_downstream
node_viewer -->|"plays media"| node_player
node_viewer -->|"views comments"| node_danmaku
node_viewer -->|"browses titles"| node_douban
node_viewer -->|"watches live"| node_live
node_viewer -.->|"plays music"| node_music
node_viewer -->|"downloads video"| node_offline
node_viewer -.->|"signs in"| node_auth
node_auth -->|"refreshes tokens"| node_refresh
node_config -->|"loads config"| node_db
node_admin -.->|"manages settings"| node_config
node_db -->|"selects backend"| node_d1
node_db -->|"selects backend"| node_postgres
node_viewer -->|"joins room"| node_watch_ui
node_watch_ui -->|"connects socket"| node_watch_socket
node_watch_socket -->|"uses events"| node_watch_types
node_detail_api -.->|"resolves source"| node_source_detail
node_source_detail -->|"loads source settings"| node_config
node_source_detail -->|"searches provider"| node_downstream
node_source_detail -.->|"uses Emby sources"| node_emby_manager
node_source_detail -.->|"uses OpenList"| node_openlist_client
node_source_detail -.->|"parses episodes"| node_video_parser
node_viewer -.->|"discovers titles"| node_tmdb_search

click node_search_ui "https://github.com/tud8951/moontvplus/blob/main/src/app/search/page.tsx"
click node_search_api "https://github.com/tud8951/moontvplus/blob/main/src/app/api/search/route.ts"
click node_downstream "https://github.com/tud8951/moontvplus/blob/main/src/lib/downstream.ts"
click node_detail_api "https://github.com/tud8951/moontvplus/blob/main/src/app/api/detail/route.ts"
click node_source_detail "https://github.com/tud8951/moontvplus/blob/main/src/app/api/source-detail/route.ts"
click node_player "https://github.com/tud8951/moontvplus/blob/main/src/app/play/page.tsx"
click node_danmaku "https://github.com/tud8951/moontvplus/blob/main/src/lib/danmaku/api.ts"
click node_douban "https://github.com/tud8951/moontvplus/blob/main/src/lib/douban.client.ts"
click node_tmdb_search "https://github.com/tud8951/moontvplus/blob/main/src/lib/tmdb.search.ts"
click node_emby_manager "https://github.com/tud8951/moontvplus/blob/main/src/lib/emby-manager.ts"
click node_openlist_client "https://github.com/tud8951/moontvplus/blob/main/src/lib/openlist.client.ts"
click node_video_parser "https://github.com/tud8951/moontvplus/blob/main/src/lib/video-parser.ts"
click node_live "https://github.com/tud8951/moontvplus/blob/main/src/app/live/page.tsx"
click node_music "https://github.com/tud8951/moontvplus/blob/main/src/app/music/page.tsx"
click node_offline "https://github.com/tud8951/moontvplus/blob/main/src/lib/offline-downloader.ts"
click node_auth "https://github.com/tud8951/moontvplus/blob/main/src/lib/auth.ts"
click node_refresh "https://github.com/tud8951/moontvplus/blob/main/src/lib/refresh-token.ts"
click node_config "https://github.com/tud8951/moontvplus/blob/main/src/lib/config.ts"
click node_admin "https://github.com/tud8951/moontvplus/blob/main/src/app/admin/page.tsx"
click node_db "https://github.com/tud8951/moontvplus/blob/main/src/lib/db.ts"
click node_db_client "https://github.com/tud8951/moontvplus/blob/main/src/lib/db.client.ts"
click node_d1 "https://github.com/tud8951/moontvplus/blob/main/src/lib/d1.db.ts"
click node_postgres "https://github.com/tud8951/moontvplus/blob/main/src/lib/postgres.db.ts"
click node_watch_ui "https://github.com/tud8951/moontvplus/blob/main/src/components/WatchRoomProvider.tsx"
click node_watch_socket "https://github.com/tud8951/moontvplus/blob/main/src/lib/watch-room-socket.ts"
click node_watch_types "https://github.com/tud8951/moontvplus/blob/main/src/types/watch-room.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_search_ui,node_search_api,node_downstream,node_detail_api,node_source_detail,node_player,node_danmaku,node_viewer toneBlue
class node_douban,node_tmdb_search,node_emby_manager,node_openlist_client,node_video_parser,node_live,node_music,node_offline toneAmber
class node_auth,node_refresh,node_db,node_db_client,node_d1,node_postgres toneMint
class node_watch_ui,node_watch_socket,node_watch_types toneRose
class node_config,node_admin toneIndigo
```

## Components

### Discovery and playback

- [Search experience](https://github.com/tud8951/moontvplus/blob/main/src/app/search/page.tsx): `src/app/search/page.tsx`
- [Aggregated search](https://github.com/tud8951/moontvplus/blob/main/src/app/api/search/route.ts): `src/app/api/search/route.ts`
- [Provider search](https://github.com/tud8951/moontvplus/blob/main/src/lib/downstream.ts): `src/lib/downstream.ts`
- [Title details](https://github.com/tud8951/moontvplus/blob/main/src/app/api/detail/route.ts): `src/app/api/detail/route.ts`
- [Source detail lookup](https://github.com/tud8951/moontvplus/blob/main/src/app/api/source-detail/route.ts): `src/app/api/source-detail/route.ts`
- [Video player](https://github.com/tud8951/moontvplus/blob/main/src/app/play/page.tsx): `src/app/play/page.tsx`
- [Danmaku](https://github.com/tud8951/moontvplus/blob/main/src/lib/danmaku/api.ts): `src/lib/danmaku/api.ts`

### Media integrations

- [Douban discovery](https://github.com/tud8951/moontvplus/blob/main/src/lib/douban.client.ts): `src/lib/douban.client.ts`
- [TMDB search](https://github.com/tud8951/moontvplus/blob/main/src/lib/tmdb.search.ts): `src/lib/tmdb.search.ts`
- [Emby integration](https://github.com/tud8951/moontvplus/blob/main/src/lib/emby-manager.ts): `src/lib/emby-manager.ts`
- [OpenList client](https://github.com/tud8951/moontvplus/blob/main/src/lib/openlist.client.ts): `src/lib/openlist.client.ts`
- [Video parsing](https://github.com/tud8951/moontvplus/blob/main/src/lib/video-parser.ts): `src/lib/video-parser.ts`
- [Live TV](https://github.com/tud8951/moontvplus/blob/main/src/app/live/page.tsx): `src/app/live/page.tsx`
- [Music library](https://github.com/tud8951/moontvplus/blob/main/src/app/music/page.tsx): `src/app/music/page.tsx`
- [Offline downloads](https://github.com/tud8951/moontvplus/blob/main/src/lib/offline-downloader.ts): `src/lib/offline-downloader.ts`

### Accounts and state

- [Authentication](https://github.com/tud8951/moontvplus/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Token refresh](https://github.com/tud8951/moontvplus/blob/main/src/lib/refresh-token.ts): `src/lib/refresh-token.ts`
- [Storage facade](https://github.com/tud8951/moontvplus/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Browser state](https://github.com/tud8951/moontvplus/blob/main/src/lib/db.client.ts): `src/lib/db.client.ts`
- [D1 storage](https://github.com/tud8951/moontvplus/blob/main/src/lib/d1.db.ts): `src/lib/d1.db.ts`
- [Postgres storage](https://github.com/tud8951/moontvplus/blob/main/src/lib/postgres.db.ts): `src/lib/postgres.db.ts`

### Social viewing

- [Watch room UI](https://github.com/tud8951/moontvplus/blob/main/src/components/WatchRoomProvider.tsx): `src/components/WatchRoomProvider.tsx`
- [Room socket server](https://github.com/tud8951/moontvplus/blob/main/src/lib/watch-room-socket.ts): `src/lib/watch-room-socket.ts`
- [Room event types](https://github.com/tud8951/moontvplus/blob/main/src/types/watch-room.ts): `src/types/watch-room.ts`

### Administration

- [Application config](https://github.com/tud8951/moontvplus/blob/main/src/lib/config.ts): `src/lib/config.ts`
- [Admin configuration](https://github.com/tud8951/moontvplus/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`

### Other components

- **Viewer**

## Connections

- Viewer → Search experience: searches
- Search experience → Aggregated search: queries
- Aggregated search → Application config: loads sources (evidence: `src/app/api/search/route.ts`)
- Aggregated search → Provider search: searches providers (evidence: `src/app/api/search/route.ts`)
- Provider search → Application config: reads settings (evidence: `src/lib/downstream.ts`)
- Viewer → Title details: opens title
- Title details → Provider search: fetches details (evidence: `src/app/api/detail/route.ts`)
- Viewer → Video player: plays media
- Viewer → Danmaku: views comments
- Viewer → Douban discovery: browses titles
- Viewer → Live TV: watches live
- Viewer → Music library: plays music
- Viewer → Offline downloads: downloads video
- Viewer → Authentication: signs in
- Authentication → Token refresh: refreshes tokens (evidence: `src/lib/refresh-token.ts`)
- Application config → Storage facade: loads config (evidence: `src/lib/config.ts`)
- Admin configuration → Application config: manages settings
- Storage facade → D1 storage: selects backend (evidence: `src/lib/db.ts`)
- Storage facade → Postgres storage: selects backend (evidence: `src/lib/db.ts`)
- Viewer → Watch room UI: joins room
- Watch room UI → Room socket server: connects socket (evidence: `src/components/WatchRoomProvider.tsx`)
- Room socket server → Room event types: uses events (evidence: `src/lib/watch-room-socket.ts`)
- Title details → Source detail lookup: resolves source
- Source detail lookup → Application config: loads source settings (evidence: `src/app/api/source-detail/route.ts`)
- Source detail lookup → Provider search: searches provider (evidence: `src/app/api/source-detail/route.ts`)
- Source detail lookup → Emby integration: uses Emby sources (evidence: `src/app/api/source-detail/route.ts`)
- Source detail lookup → OpenList client: uses OpenList (evidence: `src/app/api/source-detail/route.ts`)
- Source detail lookup → Video parsing: parses episodes (evidence: `src/app/api/source-detail/route.ts`)
- Viewer → TMDB search: discovers titles
