# dispatcharr/dispatcharr architecture

> Architecture diagram of the GitHub repository dispatcharr/dispatcharr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dispatcharr/dispatcharr
- Repository: https://github.com/dispatcharr/dispatcharr

## Overview

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.

Main entry points: [`dispatcharr/celery.py`](https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/celery.py) (Celery jobs), [`apps/channels/models.py`](https://github.com/dispatcharr/dispatcharr/blob/main/apps/channels/models.py) (Channels), [`dispatcharr/settings.py`](https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/settings.py) (Dispatcharr), [`apps/proxy/apps.py`](https://github.com/dispatcharr/dispatcharr/blob/main/apps/proxy/apps.py) (Proxy layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_dispatcharr_core["Dispatcharr<br/>django project<br/>[settings.py]"]
  node_core_control["Core control<br/>settings/auth<br/>[models.py]"]
  node_accounts["Accounts<br/>identity<br/>[models.py]"]
  node_m3u_ingest["M3U ingest<br/>source sync<br/>[models.py]"]
  node_epg_ingest["EPG ingest<br/>guide sync<br/>[models.py]"]
  node_channels_dvr["Channels<br/>live tv core<br/>[models.py]"]
  node_vod_catalog["VOD<br/>[models.py]"]
  node_connect_automation["Connect<br/>automation<br/>[models.py]"]
  node_plugins_ext["Plugins<br/>extension<br/>[models.py]"]
  node_hdhr_output["HDHomeRun<br/>compatibility api<br/>[views.py]"]
end

subgraph group_runtime["Runtime"]
  node_proxy_runtime["Proxy layer<br/>stream delivery<br/>[apps.py]"]
  node_live_proxy["Live proxy<br/>stream runtime<br/>[server.py]"]
  node_vod_proxy["VOD proxy<br/>vod runtime<br/>[views.py]"]
  node_realtime_bus["Realtime bus<br/>ws/pubsub<br/>[consumers.py]"]
  node_celery_jobs["Celery jobs<br/>async orchestration<br/>[celery.py]"]
  node_postgres[("Postgres<br/>database<br/>[base.py]")]
  node_redis[("Redis<br/>coordination<br/>[redis_pubsub.py]")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Frontend<br/>react client<br/>[main.jsx]"]
  node_api_boundary["API layer<br/>rest api<br/>[api.js]"]
end

subgraph group_deploy["Deployment"]
  node_deployment["Deploy<br/>ops/runtime<br/>[docker-compose.yml]"]
end

node_frontend_app -->|"calls"| node_api_boundary
node_frontend_app -->|"subscribes"| node_realtime_bus
node_api_boundary -->|"served by"| node_dispatcharr_core
node_dispatcharr_core -->|"loads"| node_core_control
node_core_control -->|"governs"| node_accounts
node_m3u_ingest -->|"feeds"| node_channels_dvr
node_epg_ingest -->|"enriches"| node_channels_dvr
node_channels_dvr -->|"drives"| node_proxy_runtime
node_proxy_runtime -->|"contains"| node_live_proxy
node_proxy_runtime -->|"contains"| node_vod_proxy
node_live_proxy -->|"coordinates"| node_redis
node_vod_proxy -->|"coordinates"| node_redis
node_live_proxy -->|"reads"| node_channels_dvr
node_vod_catalog -->|"served through"| node_proxy_runtime
node_hdhr_output -->|"exports"| node_channels_dvr
node_connect_automation -->|"uses"| node_core_control
node_plugins_ext -->|"extends"| node_connect_automation
node_celery_jobs -->|"runs"| node_m3u_ingest
node_celery_jobs -->|"runs"| node_epg_ingest
node_celery_jobs -->|"runs"| node_channels_dvr
node_celery_jobs -->|"runs"| node_vod_catalog
node_celery_jobs -->|"runs"| node_plugins_ext
node_dispatcharr_core -->|"persists"| node_postgres
node_dispatcharr_core -->|"coordinates"| node_redis
node_deployment -->|"starts"| node_dispatcharr_core
node_deployment -->|"starts"| node_celery_jobs
node_deployment -->|"starts"| node_proxy_runtime

click node_dispatcharr_core "https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/settings.py"
click node_core_control "https://github.com/dispatcharr/dispatcharr/blob/main/core/models.py"
click node_accounts "https://github.com/dispatcharr/dispatcharr/blob/main/apps/accounts/models.py"
click node_m3u_ingest "https://github.com/dispatcharr/dispatcharr/blob/main/apps/m3u/models.py"
click node_epg_ingest "https://github.com/dispatcharr/dispatcharr/blob/main/apps/epg/models.py"
click node_channels_dvr "https://github.com/dispatcharr/dispatcharr/blob/main/apps/channels/models.py"
click node_vod_catalog "https://github.com/dispatcharr/dispatcharr/blob/main/apps/vod/models.py"
click node_connect_automation "https://github.com/dispatcharr/dispatcharr/blob/main/apps/connect/models.py"
click node_plugins_ext "https://github.com/dispatcharr/dispatcharr/blob/main/apps/plugins/models.py"
click node_hdhr_output "https://github.com/dispatcharr/dispatcharr/blob/main/apps/hdhr/views.py"
click node_proxy_runtime "https://github.com/dispatcharr/dispatcharr/blob/main/apps/proxy/apps.py"
click node_live_proxy "https://github.com/dispatcharr/dispatcharr/blob/main/apps/proxy/live_proxy/server.py"
click node_vod_proxy "https://github.com/dispatcharr/dispatcharr/blob/main/apps/proxy/vod_proxy/views.py"
click node_realtime_bus "https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/consumers.py"
click node_celery_jobs "https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/celery.py"
click node_frontend_app "https://github.com/dispatcharr/dispatcharr/blob/main/frontend/src/main.jsx"
click node_api_boundary "https://github.com/dispatcharr/dispatcharr/blob/main/frontend/src/api.js"
click node_deployment "https://github.com/dispatcharr/dispatcharr/blob/main/docker/docker-compose.yml"
click node_postgres "https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/db/backends/postgresql_psycopg3/base.py"
click node_redis "https://github.com/dispatcharr/dispatcharr/blob/main/core/redis_pubsub.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dispatcharr_core,node_core_control,node_accounts,node_m3u_ingest,node_epg_ingest,node_channels_dvr,node_vod_catalog,node_connect_automation,node_plugins_ext,node_hdhr_output toneBlue
class node_proxy_runtime,node_live_proxy,node_vod_proxy,node_realtime_bus,node_celery_jobs,node_postgres,node_redis toneAmber
class node_frontend_app,node_api_boundary toneMint
class node_deployment toneRose
```

## Components

### Backend

Django monolith and domain apps

- [Dispatcharr](https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/settings.py): django project · Project settings, ASGI/WSGI, routing, and bootstrap · `dispatcharr/settings.py`
- [Core control](https://github.com/dispatcharr/dispatcharr/blob/main/core/models.py): settings/auth · Global settings, access control, pubsub, and admin ops · `core/models.py`
- [Accounts](https://github.com/dispatcharr/dispatcharr/blob/main/apps/accounts/models.py): identity · Users, permissions, API keys, and network restrictions · `apps/accounts/models.py`
- [M3U ingest](https://github.com/dispatcharr/dispatcharr/blob/main/apps/m3u/models.py): source sync · Provider playlists, filters, account sync, and refresh tasks · `apps/m3u/models.py`
- [EPG ingest](https://github.com/dispatcharr/dispatcharr/blob/main/apps/epg/models.py): guide sync · Program sources, parsing, matching, indexing, and refresh tasks · `apps/epg/models.py`
- [Channels](https://github.com/dispatcharr/dispatcharr/blob/main/apps/channels/models.py): live tv core · Channels, streams, numbering, recordings, and scheduling rules · `apps/channels/models.py`
- [VOD](https://github.com/dispatcharr/dispatcharr/blob/main/apps/vod/models.py): vod catalog · Movies, series, relations, logos, and metadata · `apps/vod/models.py`
- [Connect](https://github.com/dispatcharr/dispatcharr/blob/main/apps/connect/models.py): automation · Event subscriptions, webhooks, and script handlers · `apps/connect/models.py`
- [Plugins](https://github.com/dispatcharr/dispatcharr/blob/main/apps/plugins/models.py): extension · Plugin repository, loading, signed artifacts, and action execution · `apps/plugins/models.py`
- [HDHomeRun](https://github.com/dispatcharr/dispatcharr/blob/main/apps/hdhr/views.py): compatibility api · HDHomeRun-compatible surface for external media clients · `apps/hdhr/views.py`

### Runtime

Async workers, realtime, and stream delivery

- [Proxy layer](https://github.com/dispatcharr/dispatcharr/blob/main/apps/proxy/apps.py): stream delivery · Live, VOD, and HLS proxy services plus active session management · `apps/proxy/apps.py`
- [Live proxy](https://github.com/dispatcharr/dispatcharr/blob/main/apps/proxy/live_proxy/server.py): stream runtime · Upstream fetch, buffering, client management, and transport output · `apps/proxy/live_proxy/server.py`
- [VOD proxy](https://github.com/dispatcharr/dispatcharr/blob/main/apps/proxy/vod_proxy/views.py): vod runtime · VOD session handling and multi-worker stream coordination · `apps/proxy/vod_proxy/views.py`
- [Realtime bus](https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/consumers.py): ws/pubsub · WebSocket consumers, routing, Redis pubsub, and live state updates · `dispatcharr/consumers.py`
- [Celery jobs](https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/celery.py): async orchestration · Background tasks, schedulers, and periodic maintenance work · `dispatcharr/celery.py`
- [Postgres](https://github.com/dispatcharr/dispatcharr/blob/main/dispatcharr/db/backends/postgresql_psycopg3/base.py): database · Primary persistent store with custom psycopg3 backend and pooling · `dispatcharr/db/backends/postgresql_psycopg3/base.py`
- [Redis](https://github.com/dispatcharr/dispatcharr/blob/main/core/redis_pubsub.py): coordination · Locks, pubsub, stream coordination, and shared runtime state · `core/redis_pubsub.py`

### Frontend

React client and UI state layer

- [Frontend](https://github.com/dispatcharr/dispatcharr/blob/main/frontend/src/main.jsx): react client · React/Vite UI, pages, components, and store layer · `frontend/src/main.jsx`
- [API layer](https://github.com/dispatcharr/dispatcharr/blob/main/frontend/src/api.js): rest api · Frontend API client and backend REST endpoints · `frontend/src/api.js`

### Deployment

Container and process entrypoints

- [Deploy](https://github.com/dispatcharr/dispatcharr/blob/main/docker/docker-compose.yml): ops/runtime · Docker, entrypoints, Nginx, and process roles · `docker/docker-compose.yml`

## Connections

- Frontend → API layer: calls · UI data fetches and mutations go through the API client
- Frontend → Realtime bus: subscribes · Live UI state updates arrive over WebSockets
- API layer → Dispatcharr: served by · Backend routes and app bootstrap expose REST and page endpoints
- Dispatcharr → Core control: loads · Project configuration and shared control-plane logic
- Core control → Accounts: governs · Permissions, auth, and network restrictions are enforced here
- M3U ingest → Channels: feeds · Playlist and provider sync populate channel and stream models
- EPG ingest → Channels: enriches · Guide data is matched onto channels and recordings
- Channels → Proxy layer: drives · Channel state and assignments control stream delivery
- Proxy layer → Live proxy: contains · Primary live-stream delivery path
- Proxy layer → VOD proxy: contains · Separate VOD session and cleanup path
- Live proxy → Redis: coordinates · Viewer sessions, locks, and stream state use Redis
- VOD proxy → Redis: coordinates · Cross-worker session state and cleanup use Redis
- Live proxy → Channels: reads · Proxy fetches stream and channel metadata for delivery
- VOD → Proxy layer: served through · VOD content is exposed via proxy-backed playback paths
- HDHomeRun → Channels: exports · Compatible device surface is derived from live channel data
- Connect → Core control: uses · Event handling and execution obey system settings and access rules
- Plugins → Connect: extends · Plugins can respond to events and trigger actions
- Celery jobs → M3U ingest: runs · Periodic playlist sync and maintenance work
- Celery jobs → EPG ingest: runs · Guide parsing, refresh, and indexing jobs
- Celery jobs → Channels: runs · Recording, scheduling, and cleanup tasks
- Celery jobs → VOD: runs · Metadata and relation maintenance tasks
- Celery jobs → Plugins: runs · Plugin loading and action execution tasks
- Dispatcharr → Postgres: persists · Primary application state is stored in Postgres
- Dispatcharr → Redis: coordinates · Pubsub and distributed runtime coordination
- Deploy → Dispatcharr: starts · Web/API process entrypoint
- Deploy → Celery jobs: starts · Worker process entrypoint
- Deploy → Proxy layer: starts · Stream proxy process entrypoint