dispatcharr/dispatcharr

1. Overall shape

Dispatcharr is a Django monolith split into many domain apps, with a React/Vite frontend in frontend/, plus background workers and stream proxy services. The backend serves both the web UI and the public APIs that the frontend consumes.

2. Core runtime stack

The server side is Python-based (manage.py, dispatcharr/). It uses Django + DRF-style API modules, Celery for async work, ASGI/WebSockets for live updates, and a custom PostgreSQL backend/pool under dispatcharr/db/. Redis is used for pub/sub, locks, and streaming coordination.

3. Frontend boundary

The React app is a separate client that talks to backend APIs from frontend/src/api.js and subscribes to live state via frontend/src/WebSocket.jsx. It is organized around pages like Channels, Guide, DVR, VODs, Plugins, Settings, Users, and a store layer that mirrors backend domains.

4. Identity, access, and system settings

apps/accounts/ and core/ hold user management, permissions, API keys, network restrictions, and global system settings. This is the control plane for authentication and authorization across the rest of the system.

5. Content ingestion and synchronization

apps/m3u/ and apps/epg/ are the main ingestion pipelines. M3U handles playlist/provider accounts and sync logic; EPG handles program data sources, parsing, matching, indexing, and refresh tasks. These apps feed the channel catalog and guide data used everywhere else.

6. Channel and recording domain

apps/channels/ is the central live-TV model: channels, streams, groups, numbering, matching, recordings, and recurring recording rules. It also owns a lot of the scheduling and DVR pipeline logic, so it is the core business domain that ties sources, EPG, and proxies together.

7. Live streaming proxy layer

apps/proxy/ is the runtime stream delivery layer. It contains live proxy code for fetching upstream streams, buffering, client management, and output generation, plus VOD proxy and HLS proxy paths. This layer is where the system turns backend source streams into client-facing transport streams and manages active viewer sessions.

8. Output and compatibility services

apps/hdhr/ exposes an HDHomeRun-compatible surface for media-center integrations, while apps/output/ and parts of apps/proxy/ handle stream export formats and profiles. The architecture supports multiple output targets such as live clients, TV guide integrations, and media-server DVR discovery.

9. Video on demand

apps/vod/ manages movies, series, relations, logos, and related metadata. It sits alongside the live-TV domain but is separate from it, with its own API, serializers, and tasks.

10. Automation and extensibility

apps/connect/ is an event subscription/automation subsystem with webhook and script handlers. apps/plugins/ adds a plugin repository, loading, action execution, and signed plugin artifacts, making it a separate extension boundary from the core product logic.

11. Background jobs and orchestration

Many apps have tasks.py, scheduler.py, or periodic-task migrations, indicating that refreshes, syncs, notifications, backups, and stream maintenance are executed asynchronously. Celery is the main orchestration mechanism for long-running or scheduled work.

12. Realtime state and notifications

dispatcharr/consumers.py, dispatcharr/routing.py, and core/redis_pubsub.py indicate a WebSocket and pub/sub channel for live state changes. The frontend’s stats, notifications, and stream-monitoring views depend on this realtime layer rather than polling alone.

13. Deployment topology

The repo includes Dockerfiles, compose files, Nginx config, and separate entrypoints for the web app and Celery workers. That means the deployment is designed to be split into web/API, worker, Redis, and Postgres roles, with an all-in-one option for simpler installs.

14. Operational boundaries

core/management/commands/ and dispatcharr/ utilities cover operational tasks such as DB reset, network access resets, and process control. The architecture clearly distinguishes user-facing features from admin/maintenance tooling.

15. Data flow summary

External sources enter through M3U/EPG/VOD/stream-provider integrations, are persisted in Postgres, enriched by background jobs, and then exposed through REST APIs, WebSockets, and proxy endpoints to the frontend and to external clients like Plex/Emby/Jellyfin via HDHomeRun or IPTV-compatible exports.