Watcharr

Watcharr is a lightweight, self‑hosted media tracking platform that lets developers build and extend personal catalogues for movies, TV shows, anime, and even video games. At its core it exposes a REST‑ful API for CRUD operations on media items, status updates, ratings and watch lists while providing a modern SvelteKit front‑end that consumes the same API. The architecture is intentionally minimalistic: a single Go binary serves both the API and static assets, enabling zero‑dependency deployments that fit comfortably in Docker containers or bare metal.

Key Features

• Unified media model – Movies, TV shows, anime and games share a single schema with polymorphic fields for metadata (e.g., episode count, platform, release dates).
• Status & rating workflow – Developers can hook into status transitions (planned → watching → completed) via webhooks or the API, making it trivial to sync with external services like Plex or Trakt.
• Search & discover – An internal Elasticsearch index (or optional SQLite full‑text search) powers fast title lookup and recommendation endpoints.
• User management – JWT‑based authentication, role‑based access control and optional OAuth integration are baked in.

Technical Stack

The Go service is compiled into a single statically linked binary, which reduces runtime dependencies and simplifies deployment. The API follows idiomatic REST conventions with pagination (limit, offset) and filtering via query parameters. All endpoints are documented in an OpenAPI 3.0 spec that can be generated from Go annotations.

Core Capabilities & APIs

• Media CRUD – POST /api/media, GET /api/media/{id}, PATCH /api/media/{id}
• Status transitions – POST /api/media/{id}/status (payload: { status: "watching" })
• Batch operations – POST /api/media/batch accepts an array of media objects for bulk imports.
• Webhooks – Configurable URL endpoints that receive JSON payloads on status changes, rating updates or new media additions.
• GraphQL – Optional GraphQL endpoint (/graphql) for flexible querying when the client needs to fetch nested data (e.g., episodes of a series) in one round‑trip.
• SDKs – A Go client library (watcharr-sdk-go) and a TypeScript SDK are available, generated from the OpenAPI spec.

Deployment & Infrastructure

Watcharr’s single‑binary design makes it ideal for micro‑service architectures. It can run in:

• Docker – docker pull ghcr.io/sbondco/watcharr:latest
• Kubernetes – Helm chart exposes replicaCount, persistent volume claim, and external database connection strings.
• Bare metal – Binary can be copied to /usr/local/bin/watcharr and started with a systemd unit.
• Scaling – Stateless API servers can be horizontally scaled; the database layer (PostgreSQL) handles concurrent writes, while read replicas can serve discovery queries.

Integration & Extensibility

• Plugin system – A simple Go plugin interface (watcharr-plugin) allows developers to write extensions that run in the same process. Examples include a Trakt sync plugin, custom metadata enrichers, or UI theme overrides.
• Webhook & API hooks – External services can react to state changes without polling, making it suitable for home‑media automation (e.g., marking a series as watched in Plex).
• Custom fields – The media schema can be extended via a metadata JSONB column, enabling domain‑specific attributes (e.g., game genre tags).
• CLI – A command‑line tool (watcharr-cli) can perform bulk imports, export CSVs, or trigger status updates from scripts.

Developer Experience

• Configuration – A single config.yaml file covers database URLs, API ports, JWT secrets and webhook endpoints. Environment variables override the file for CI pipelines.
• Documentation – The official docs (https://watcharr.app/docs) include a comprehensive API reference, deployment guides and plugin tutorials.
• Community – Active GitHub discussions, a Matrix channel (#watcharr:matrix.org) and open issues ensure quick support.
• Testing – Unit tests cover 80% of the API layer, and integration tests run against a Dockerized PostgreSQL instance in CI.

Use Cases