# moldytaint/cinephage architecture

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

- Interactive diagram: https://gitdiagram.com/moldytaint/cinephage
- Repository: https://github.com/moldytaint/cinephage

## Overview

1. **Overall shape**
   - Cinephage is a single-process, self-hosted media management platform built on **SvelteKit/Node.js**.
   - The app is split into a **browser UI** under `src/routes` and `src/lib/components`, and a **server-side service layer** under `src/lib/server`.
   - It is designed as one unified system for media library management, discovery, downloads, streaming, subtitles, live TV, and background automation.

2. **Primary architectural boundary: UI vs server**
   - The Svelte pages render the operator interface for library, discover, settings, live TV, smart lists, and monitoring.
   - Most user actions hit **API endpoints in `src/routes/api/**`**, which act as thin controllers.
   - Those handlers delegate to server services rather than containing business logic themselves.

3. **Core data backbone**
   - The repository centers on a **single application database** managed through `src/lib/server/db` and schema sync logic.
   - Nearly every subsystem reads and writes shared records: library items, indexer configs, download clients, subtitle providers, live TV accounts, tasks, queue/history, and settings.
   - `data/` contains bundled metadata/configuration assets, especially indexer definitions and channel logos, while persistent runtime state is expected in the deployed config volume.

4. **Library management subsystem**
   - `src/lib/server/library` is the core media-library engine.
   - It handles folder scanning, media matching, file/import workflows, rename previews, naming rules, quality backfill, unmatched items, and auto-search-on-add.
   - The library layer is the main consumer of filesystem scanning, metadata matching, TMDb enrichment, and downstream search/download actions.

5. **Discovery, metadata, and smart lists**
   - Discovery and metadata features are centered around **TMDb** integration (`src/lib/server/tmdb.ts`, `src/lib/server/quality/TmdbMatcher.ts`, `src/lib/tmdb.ts`).
   - Smart lists add a second discovery path: external providers and presets in `src/lib/server/smartlists` and `data/external-lists/presets`.
   - The flow is typically: external metadata source → resolver/provider → database-backed list definition → library auto-add or preview UI.

6. **Indexer and release search pipeline**
   - Indexer management is a major subsystem under `src/lib/server/indexers`.
   - It loads YAML definitions from `data/indexers/definitions`, authenticates to provider-specific sites, handles rate limiting, Cloudflare/captcha challenges, parses release data, and normalizes results across torrent, usenet, and streaming-style protocols.
   - Search orchestration deduplicates and ranks releases before returning them to the library, monitoring, or manual search UI.

7. **Download clients and acquisition**
   - Download integration lives in `src/lib/server/downloadClients`.
   - It abstracts multiple backends: qBittorrent, SABnzbd, NZBGet, Deluge, Transmission, rTorrent, aria2, and NZBMount.
   - The higher-level download flow is: search result → release decision → client-specific adapter → tracked download state / monitoring / import.

8. **Streaming subsystem**
   - Streaming is a distinct execution path under `src/lib/server/streaming`.
   - It supports `.strm` generation, URL resolution, provider lookup, validation, prefetching, caching, and proxying.
   - There are separate branches for **hosted streaming providers**, **usenet streaming**, and **subtitle injection / HLS rewriting**, which means the streaming path is not just file serving; it is a resolver + cache + proxy pipeline.

9. **Usenet streaming and mounted access**
   - Usenet playback is implemented as a specialized subsystem inside streaming: `src/lib/server/streaming/usenet` and `src/lib/server/downloadClients/nzbmount`.
   - It uses NNTP connections, segment caching, yEnc decoding, and seekable stream assembly to serve content without a full download-first workflow.
   - This is a clear boundary: the app can either delegate to a download client or act as a direct stream assembler.

10. **Live TV / IPTV subsystem**
   - Live TV is a full subsystem under `src/lib/server/livetv`.
   - It manages accounts/providers, channel lineups, EPG scheduling and sync, portal scanning, channel categories, and HLS stream handling.
   - Provider adapters include M3U, Stalker, Xstream, and IPTV-org-related discovery, with separate UI routes and API endpoints for lineup, EPG, portal scans, and playlist generation.

11. **Subtitle management pipeline**
   - Subtitle functionality is handled by `src/lib/server/subtitles`.
   - It includes provider adapters, search/download/import, scoring, language profiles, throttling, and synchronization against the library.
   - The subsystem is integrated into both monitoring and streaming so subtitles can be fetched proactively and also delivered alongside playback.

12. **Monitoring, tasks, and background automation**
   - Automated activity is coordinated by `src/lib/server/monitoring` and `src/lib/server/tasks`.
   - Monitoring tasks cover missing content, upgrades, cutoff unmet items, subtitle upgrades, new episodes, pending releases, and smart-list refreshes.
   - Task history, scheduling, cancellation, and execution context provide the background-job boundary for the rest of the system.

13. **Workers and async execution**
   - `src/lib/server/workers` centralizes long-running or isolated operations: search, import, stream, subtitle search, portal scanning, channel sync, and task execution.
   - The worker layer acts as the concurrency boundary so expensive operations do not block request handlers.
   - UI/API actions often enqueue work, then read back status through SSE or status endpoints.

14. **Cross-cutting infrastructure and safety**
   - The app includes SSRF protection, URL security, path guards, filesystem overlap checks, and redaction utilities because it touches local media paths and untrusted external providers.
   - A built-in captcha/Cloudflare solving stack is part of the server runtime, replacing an external FlareSolverr-style service.
   - SSE support (`src/lib/server/sse.ts`, `src/lib/sse`) provides live progress/status updates to the UI for tasks, queueing, and scans.

15. **Deployment and runtime assumptions**
   - The repo is packaged for containerized deployment with a `Dockerfile`, `docker-compose.yaml`, and entrypoint scripts, with environment-driven config from `.env.example`.
   - Documentation and deployment files show the system expects mounted volumes for configuration, media, and downloads, making the local filesystem and external provider network the key integration boundaries.

Main entry points: [`src/lib/server/services`](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/services) (Service layer), [`src/routes/api`](https://github.com/moldytaint/cinephage/tree/main/src/routes/api) (API routes), [`src/routes`](https://github.com/moldytaint/cinephage/tree/main/src/routes) (Routes), [`src/lib/server/indexers`](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/indexers) (Indexers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_routes_ui["Routes<br/>svelte pages"]
  node_components_ui["Components"]
end

subgraph group_api["API"]
  node_api_routes["API routes<br/>request handlers"]
end

subgraph group_core["Server core"]
  node_services["Service layer<br/>orchestration"]
  node_library["Library<br/>media engine"]
  node_discover_tmdb["TMDb<br/>metadata<br/>[tmdb.ts]"]
  node_smartlists["Smart lists<br/>list engine"]
  node_indexers["Indexers<br/>search pipeline"]
  node_downloads["Downloads<br/>acquisition"]
  node_download_clients["Clients<br/>backend adapters"]
  node_streaming["Streaming<br/>playback pipeline"]
  node_usenet_streaming["Usenet stream<br/>nntp playback"]
  node_livetv["Live TV<br/>iptv subsystem"]
  node_subtitles["Subtitles<br/>subtitle pipeline"]
  node_monitoring["Monitoring<br/>automation"]
end

subgraph group_infra["Infrastructure"]
  node_db[("Database<br/>app db")]
  node_tasks["Tasks<br/>job system"]
  node_workers["Workers<br/>async runtime"]
  node_sse["SSE<br/>live status<br/>[sse.ts]"]
  node_safety["Safety<br/>guards<br/>[ssrf-protection.ts]"]
end

subgraph group_assets["Data & deploy"]
  node_data_assets["Data assets<br/>bundled definitions"]
  node_deploy["Deploy<br/>runtime packaging"]
end

node_routes_ui -->|"uses"| node_api_routes
node_components_ui -->|"renders"| node_routes_ui
node_api_routes -->|"delegates"| node_services
node_services -->|"reads/writes"| node_db
node_services -->|"orchestrates"| node_library
node_services -->|"enriches"| node_discover_tmdb
node_services -->|"drives"| node_smartlists
node_services -->|"searches"| node_indexers
node_services -->|"acquires"| node_downloads
node_downloads -->|"adapts"| node_download_clients
node_services -->|"streams"| node_streaming
node_streaming -->|"specializes"| node_usenet_streaming
node_services -->|"manages"| node_livetv
node_services -->|"coordinates"| node_subtitles
node_services -->|"schedules"| node_monitoring
node_monitoring -->|"enqueues"| node_tasks
node_api_routes -->|"enqueues"| node_workers
node_workers -->|"reports"| node_sse
node_api_routes -->|"streams"| node_sse
node_services -->|"guards"| node_safety
node_indexers -->|"loads"| node_data_assets
node_livetv -->|"uses"| node_data_assets
node_deploy -.->|"hosts"| node_api_routes

click node_routes_ui "https://github.com/moldytaint/cinephage/tree/main/src/routes"
click node_components_ui "https://github.com/moldytaint/cinephage/tree/main/src/lib/components"
click node_api_routes "https://github.com/moldytaint/cinephage/tree/main/src/routes/api"
click node_db "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/db"
click node_services "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/services"
click node_library "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/library"
click node_discover_tmdb "https://github.com/moldytaint/cinephage/blob/main/src/lib/server/tmdb.ts"
click node_smartlists "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/smartlists"
click node_indexers "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/indexers"
click node_downloads "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/downloads"
click node_download_clients "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/downloadClients"
click node_streaming "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/streaming"
click node_usenet_streaming "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/streaming/usenet"
click node_livetv "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/livetv"
click node_subtitles "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/subtitles"
click node_monitoring "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/monitoring"
click node_tasks "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/tasks"
click node_workers "https://github.com/moldytaint/cinephage/tree/main/src/lib/server/workers"
click node_sse "https://github.com/moldytaint/cinephage/blob/main/src/lib/server/sse.ts"
click node_safety "https://github.com/moldytaint/cinephage/blob/main/src/lib/server/http/ssrf-protection.ts"
click node_data_assets "https://github.com/moldytaint/cinephage/tree/main/data"
click node_deploy "https://github.com/moldytaint/cinephage/tree/main/Dockerfile"

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_routes_ui,node_components_ui toneBlue
class node_api_routes toneAmber
class node_services,node_library,node_discover_tmdb,node_smartlists,node_indexers,node_downloads,node_download_clients,node_streaming,node_usenet_streaming,node_livetv,node_subtitles,node_monitoring toneMint
class node_db,node_tasks,node_workers,node_sse,node_safety toneRose
class node_data_assets,node_deploy toneIndigo
```

## Components

### UI

Browser-facing SvelteKit pages and shared components

- [Routes](https://github.com/moldytaint/cinephage/tree/main/src/routes): svelte pages · Operator-facing pages for library, discover, settings, live TV, tasks, and monitoring · `src/routes`
- [Components](https://github.com/moldytaint/cinephage/tree/main/src/lib/components): svelte components · Reusable UI components grouped by feature area · `src/lib/components`

### API

Thin route handlers and transport endpoints

- [API routes](https://github.com/moldytaint/cinephage/tree/main/src/routes/api): request handlers · SvelteKit endpoints that expose app operations and data · `src/routes/api`

### Server core

Business logic and orchestration services

- [Service layer](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/services): orchestration · Shared application services and background service manager · `src/lib/server/services`
- [Library](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/library): media engine · Scanning, matching, importing, renaming, backfill, and auto-search on add · `src/lib/server/library`
- [TMDb](https://github.com/moldytaint/cinephage/blob/main/src/lib/server/tmdb.ts): metadata · Metadata and discovery integration for titles, people, and artwork · `src/lib/server/tmdb.ts`
- [Smart lists](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/smartlists): list engine · External-source backed list definitions, presets, and preview/refresh logic · `src/lib/server/smartlists`
- [Indexers](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/indexers): search pipeline · Loads provider definitions, authenticates, queries, parses, and ranks releases · `src/lib/server/indexers`
- [Downloads](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/downloads): acquisition · Release decision, grab, client abstraction, monitoring, and import flow · `src/lib/server/downloads`
- [Clients](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/downloadClients): backend adapters · qBittorrent, SABnzbd, NZBGet, Deluge, Transmission, rTorrent, aria2, and NZBMount adapters · `src/lib/server/downloadClients`
- [Streaming](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/streaming): playback pipeline · Stream resolution, caching, proxying, strm generation, validation, subtitle injection, and HLS rewriting · `src/lib/server/streaming`
- [Usenet stream](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/streaming/usenet): nntp playback · Seekable stream assembly, segment caching, yEnc decoding, and NNTP access · `src/lib/server/streaming/usenet`
- [Live TV](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/livetv): iptv subsystem · Accounts, providers, lineups, categories, EPG sync, portal scans, and channel streaming · `src/lib/server/livetv`
- [Subtitles](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/subtitles): subtitle pipeline · Provider search, scoring, download, import, sync, and language profiles · `src/lib/server/subtitles`
- [Monitoring](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/monitoring): automation · Background checks for missing content, upgrades, subtitles, and pending releases · `src/lib/server/monitoring`

### Infrastructure

Persistence, safety, workers, and runtime plumbing

- [Database](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/db): app db · Shared application database and schema sync layer · `src/lib/server/db`
- [Tasks](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/tasks): job system · Task registry, scheduling, history, cancellation, and execution context · `src/lib/server/tasks`
- [Workers](https://github.com/moldytaint/cinephage/tree/main/src/lib/server/workers): async runtime · Isolated workers for search, import, stream, subtitle search, scans, and tasks · `src/lib/server/workers`
- [SSE](https://github.com/moldytaint/cinephage/blob/main/src/lib/server/sse.ts): live status · Server-sent events used for progress and status streaming to the UI · `src/lib/server/sse.ts`
- [Safety](https://github.com/moldytaint/cinephage/blob/main/src/lib/server/http/ssrf-protection.ts): guards · SSRF protection, URL security, path guards, overlap checks, and redaction · `src/lib/server/http/ssrf-protection.ts`

### Data & deploy

Bundled definitions and deployment/runtime assets

- [Data assets](https://github.com/moldytaint/cinephage/tree/main/data): bundled definitions · Indexer YAML definitions, external list presets, and channel logos · `data`
- [Deploy](https://github.com/moldytaint/cinephage/tree/main/Dockerfile): runtime packaging · Container, service, and entrypoint assets for self-hosted deployment · `Dockerfile`

## Connections

- Routes → API routes: uses · Pages call API endpoints for mutations and refreshes
- Components → Routes: renders · Shared feature components are assembled into pages
- API routes → Service layer: delegates · Handlers keep logic thin and forward to services
- Service layer → Database: reads/writes · Services persist shared application state
- Service layer → Library: orchestrates · Service layer exposes library operations and automation hooks
- Service layer → TMDb: enriches · Discovery and matching use TMDb metadata
- Service layer → Smart lists: drives · List definitions feed discovery and auto-add workflows
- Service layer → Indexers: searches · Release search and normalization run through indexers
- Service layer → Downloads: acquires · Acquisition decisions and download management are coordinated here
- Downloads → Clients: adapts · Client-specific backends execute the chosen grab
- Service layer → Streaming: streams · Playback resolution and proxying are handled by streaming services
- Streaming → Usenet stream: specializes · Usenet playback is a dedicated stream path
- Service layer → Live TV: manages · Live TV providers, lineups, EPG, and channels are managed centrally
- Service layer → Subtitles: coordinates · Subtitle search, scoring, and sync are integrated into app flows
- Service layer → Monitoring: schedules · Background automation is owned by monitoring services
- Monitoring → Tasks: enqueues · Monitoring work becomes scheduled task execution
- API routes → Workers: enqueues · Long-running actions are offloaded to workers
- Workers → SSE: reports · Workers publish live progress and status updates
- API routes → SSE: streams · API status endpoints feed the UI via SSE
- Service layer → Safety: guards · External access and filesystem operations are constrained
- Indexers → Data assets: loads · Provider definitions are bundled in the repository
- Live TV → Data assets: uses · Channel logos and related assets support lineup display
- Deploy → API routes: hosts · Deployment assets run the SvelteKit server and API
