Overseerr

Overseerr is a lightweight, full‑stack web application that orchestrates media request workflows for self‑hosted Plex environments. From a developer’s perspective, it exposes a RESTful API and a GraphQL‑style query interface that can be consumed by custom front‑ends or automation scripts. The core of the system is a request engine that translates user intents into actions against Sonarr, Radarr, or other future integrations, while maintaining a persistent audit trail in a PostgreSQL database. The app’s architecture is intentionally modular: each service (Plex, Sonarr, Radarr) runs behind a dedicated adapter layer that abstracts API differences and handles authentication tokens, enabling rapid extension to new media managers.

• Backend: Node.js (v18+) with Express as the HTTP framework. TypeScript is used for type safety, and the codebase follows a layered architecture (controllers → services → repositories). The request queue is implemented using BullMQ, backed by Redis for distributed job processing and retry handling.
• Database: PostgreSQL 13+ stores users, permissions, requests, and audit logs. The schema is versioned with Knex migrations, allowing seamless upgrades in containerized deployments.
• Frontend: React 18 with Vite for fast dev builds. UI components are built with Tailwind CSS, providing a mobile‑first design that scales across desktop and touch devices. State is managed via Redux Toolkit, while RTK Query handles API interactions.
• Containerization: A single Docker image (sctx/overseerr) exposes the web server on port 5055. The Docker Compose example ships a Redis container and a PostgreSQL instance, simplifying the “bring‑up” process for developers.
• Observability: The app emits structured logs to STDOUT, which can be captured by ELK/EFK stacks. Health checks are exposed at /health, and Prometheus metrics can be scraped via an optional exporter.

• Plex Integration: OAuth2 authentication, library scans, and user‑level access control. The Plex adapter can enumerate media items, exposing metadata such as ratings, cast, and collection tags.
• Sonarr/Radarr Orchestration: Request creation, approval workflows, and automatic quality profile selection. Advanced requests allow custom destination folders, profiles, and indexer overrides.
• Granular Permissions: Role‑based access control (RBAC) with fine‑grained scopes (request:create, request:approve, plex:view). Permissions are stored in the database and enforced by middleware.
• Notification Hooks: Webhooks, Telegram, Discord, and email notifications can be configured per request status. The webhook payload is JSON‑structured and extensible.
• API Documentation: Swagger/OpenAPI specs are auto‑generated from TypeScript decorators and hosted at /api-docs. The docs include example payloads for request creation, approval, and user management.

Overseerr is designed to run in any environment that supports Docker or Kubernetes. The single‑container image can be deployed on a Raspberry Pi, NAS, or cloud VM with minimal resource requirements (512 MiB RAM, 1 CPU). For production workloads, a Helm chart is available that provisions PostgreSQL and Redis via StatefulSets. Horizontal scaling of the web tier is straightforward: multiple instances can share a Redis‑backed BullMQ queue, ensuring that request processing remains consistent across replicas.

The adapter pattern used for Plex, Sonarr, and Radarr is fully extensible. Developers can implement a new adapter by conforming to the IMediaProvider interface and registering it in the service container. The plugin system is exposed via a simple directory (/plugins) where Node modules can export hooks into request lifecycle events (e.g., onRequestApproved). Webhooks provide a declarative way to integrate with external CI/CD pipelines or home‑automation systems.

• Configuration: All settings are exposed through environment variables (PLEX_TOKEN, SONARR_URL, REDIS_URL). The UI also offers a settings page for non‑critical options, reducing the need to edit files.
• Documentation: The official docs are hosted at docs.overseerr.dev and include a comprehensive API reference, deployment guides, and developer tutorials. The codebase is well‑commented, with JSDoc annotations that aid IDE tooling.
• Community: A vibrant Discord server and GitHub Discussions channel provide rapid feedback. The project follows a transparent issue‑tracking workflow, with labels for enhancement, bug, and question. All contributors are recognized via the All‑Contributors badge.

• Home Media Servers: A household with Plex can deploy Overseerr to delegate media requests among family members, ensuring that new content is queued and approved automatically.
• Small Media Libraries: Community media centers or small production houses can use Overseerr to manage request queues for shared libraries, integrating with Sonarr/Radarr for automated downloads.
• Automation Pipelines: Developers can hook Overseerr’s webhooks into CI/CD workflows, triggering downstream processes (e.g., transcoding jobs) when a request is approved.
• Custom Front‑ends: The open API allows building mobile or desktop clients that mirror the web UI but fit specific UX requirements.

• Open Source & GPL‑like License: No licensing fees, full source control, and the ability to modify core logic.
• Performance: Node.js + Redis provides low‑