Reiverr

Reiverr is a self‑hosted media orchestration platform that consolidates discovery, metadata enrichment, and playback across multiple streaming backends. From a developer’s perspective it behaves as a lightweight microservice that exposes a GraphQL/REST API for querying The Movie Database (TMDB) and orchestrating playback through pluggable adapters. The core goal is to provide a single point of entry for media consumption while keeping the system modular enough to support future integrations such as Plex, Emby, or custom RTSP streams.

Architecture & Technical Stack

Reiverr is built on a Node.js 18+ runtime with TypeScript for type safety. The front‑end is a modern SPA rendered by React (or a similar framework) and served via an Express server. The back‑end is split into isolated “packages” under backend/packages/, each representing a functional domain (e.g., TMDB discovery, Jellyfin adapter, Torrent‑Stream wrapper). These packages communicate over a lightweight event bus and expose HTTP endpoints that the UI consumes. Data persistence is handled by a local SQLite database (or an optional external PostgreSQL instance) to store user credentials, plugin state, and cache of TMDB queries. JWT tokens signed with a configurable secret are used for stateless authentication, allowing the service to run in containerized environments without shared session stores.

Core Capabilities & APIs

• TMDB Discovery: Endpoints for trending, recommendations, search, and detailed media info. Developers can extend these by injecting custom query parameters or creating new discovery services.
• Playback Plugins: A well‑defined plugin API (backend/packages/plugin-api/) lets developers write adapters that translate media identifiers into playable URLs. Two bundled plugins—Jellyfin and Torrent‑Stream (Jackett dependent)—demonstrate the pattern. Plugins expose a getPlayableUrl(mediaId) contract and optional metadata enrichment hooks.
• Webhooks & Events: The system emits events on media selection, playback start/stop, and plugin errors. External services can subscribe via HTTP callbacks to integrate with home‑automation platforms or analytics dashboards.
• Configuration API: A /config endpoint allows runtime modification of TMDB keys, plugin directories, and authentication settings without restarting the container.

Deployment & Infrastructure

Reiverr ships as a pre‑built OCI image on GitHub Container Registry, making Docker deployment trivial. The recommended run configuration mounts two volumes: one for persistent config (/config) and another for plugin binaries (/plugins). Because the application is stateless apart from its SQLite store, it scales horizontally by running multiple instances behind a reverse proxy that load‑balances on the /api endpoint. Container health checks expose /healthz, and the service can be orchestrated by Kubernetes or Docker Swarm using standard annotations for liveness/readiness probes.

Integration & Extensibility

The plugin architecture is intentionally open‑ended. Developers can fork the plugin-api package, implement a new adapter, and publish it to the /plugins directory. The UI automatically discovers available plugins by scanning this directory at startup, allowing zero‑config integration of new backends. Additionally, Reiverr exposes a public REST interface that external systems (e.g., a home‑automation assistant) can consume to trigger searches or retrieve playback URLs, enabling deep integration into custom workflows.

Developer Experience

Documentation is concise but covers all major concepts: installation, environment variables, plugin development, and API usage. The codebase follows TypeScript conventions, making IDE auto‑completion highly effective. Community support is still evolving; contributors are encouraged to open issues or pull requests, and the project maintains a dedicated Discord channel for real‑time discussion. The licensing is permissive (MIT), allowing commercial use without license fees.

Use Cases

• Smart TV Companion: Host Reiverr on a NAS or Raspberry Pi and use the web UI on any Tizen/Samsung Smart TV for on‑the‑fly discovery and playback through Jellyfin or Torrent‑Stream.
• Home Media Server: Integrate Reiverr with existing Plex or Emby installations to provide a unified search and playback front‑end while keeping the media libraries isolated.
• Developer Sandbox: Use Reiverr as a playground for testing new streaming protocols or metadata enrichment pipelines before deploying them to production.
• Automated Media Retrieval: Hook Reiverr’s webhooks into a home‑automation system to trigger media playback on demand from voice assistants.

Advantages Over Alternatives

Reiverr offers a lightweight, container‑friendly footprint compared to monolithic platforms like Overseerr. Its explicit plugin system removes the need for custom middleware, and the use of a single database keeps state management simple. Performance is optimized by caching TMDB responses in SQLite, and the stateless JWT approach eliminates session drift across restarts. Licensing freedom (MIT) removes vendor lock‑in, making it attractive for developers who need full control over the media stack.