How moldytaint/cinephage works
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: services Service layer · api API routes · routes Routes · indexers Indexers
Components 22
UI
Browser-facing SvelteKit pages and shared components
- Routes · Operator-facing pages for library, discover, settings, live TV, tasks, and monitoring
src/routes - Components · Reusable UI components grouped by feature area
src/lib/components
API
Thin route handlers and transport endpoints
- API routes · SvelteKit endpoints that expose app operations and data
src/routes/api
Server core
Business logic and orchestration services
- Service layer · Shared application services and background service manager
src/lib/server/services - Library · Scanning, matching, importing, renaming, backfill, and auto-search on add
src/lib/server/library - TMDb · Metadata and discovery integration for titles, people, and artwork
src/lib/server/tmdb.ts - Smart lists · External-source backed list definitions, presets, and preview/refresh logic
src/lib/server/smartlists - Indexers · Loads provider definitions, authenticates, queries, parses, and ranks releases
src/lib/server/indexers - Downloads · Release decision, grab, client abstraction, monitoring, and import flow
src/lib/server/downloads - Clients · qBittorrent, SABnzbd, NZBGet, Deluge, Transmission, rTorrent, aria2, and NZBMount adapters
src/lib/server/downloadClients - Streaming · Stream resolution, caching, proxying, strm generation, validation, subtitle injection, and HLS rewriting
src/lib/server/streaming - Usenet stream · Seekable stream assembly, segment caching, yEnc decoding, and NNTP access
src/lib/server/streaming/usenet - Live TV · Accounts, providers, lineups, categories, EPG sync, portal scans, and channel streaming
src/lib/server/livetv - Subtitles · Provider search, scoring, download, import, sync, and language profiles
src/lib/server/subtitles - Monitoring · Background checks for missing content, upgrades, subtitles, and pending releases
src/lib/server/monitoring
Infrastructure
Persistence, safety, workers, and runtime plumbing
- Database · Shared application database and schema sync layer
src/lib/server/db - Tasks · Task registry, scheduling, history, cancellation, and execution context
src/lib/server/tasks - Workers · Isolated workers for search, import, stream, subtitle search, scans, and tasks
src/lib/server/workers - SSE · Server-sent events used for progress and status streaming to the UI
src/lib/server/sse.ts - Safety · 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 · Indexer YAML definitions, external list presets, and channel logos
data - Deploy · Container, service, and entrypoint assets for self-hosted deployment
Dockerfile
Connections 23
- 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