# chocobozzz/peertube architecture

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

- Interactive diagram: https://gitdiagram.com/chocobozzz/peertube
- Repository: https://github.com/chocobozzz/peertube

## Overview

#### Purpose and deployable entry points
PeerTube is a federated video-hosting platform: instances publish, stream, moderate, and exchange video/channel activity through ActivityPub, with browser P2P delivery and optional inter-instance redundancy. The primary Node.js server starts at `server/server.ts`; the Angular web client at `client/src/main.ts`. Separate Node executables provide automation and remote media workers: `apps/peertube-cli/src/peertube.ts` and `apps/peertube-runner/src/peertube-runner.ts`.

#### HTTP application and persistence boundary
The server is an Express-style application organized around controllers, authentication/validation middleware, domain libraries, and Sequelize-backed models. REST endpoints are grouped by concern—videos, users, search, administration, runners—under `server/core/controllers/api/`; request authorization, rate limiting, ActivityPub checks, and input validation occur before controller logic in `server/core/middlewares/`. Persistent entities include actors, users, videos/files, follows, jobs, runners, moderation, and statistics in `server/core/models/`. Startup loads configuration, database connectivity, installation state, and ordered migrations through `server/core/initializers/`.

#### Video ingest, media lifecycle, and asynchronous jobs
Upload/import/live endpoints create or update video state, then delegate expensive work to the internal job queue. The queue and handlers cover imports, HLS/web-video transcoding, studio edits, thumbnails/storyboards, transcription, ActivityPub delivery, storage moves, and notifications: `server/core/lib/job-queue/job-queue.ts`, `server/core/lib/job-queue/handlers/`, and `server/core/lib/video-post-import.ts`. Media processing is built around FFmpeg abstractions in `packages/ffmpeg/src/`, while the server’s transcoding orchestration selects local queued work or remote runner work under `server/core/lib/transcoding/`.

#### Distributed runners and transcription
Instances can offload media-heavy work to registered PeerTube runners. Server-side runner registration, job dispatch, and state handling live in `server/core/lib/runners/` and `server/core/controllers/api/runners/`; the runner process exposes registration, job processing, and IPC coordination in `apps/peertube-runner/src/server/` and `apps/peertube-runner/src/shared/ipc/`. Supported remote jobs include VOD and live transcoding, studio processing, storyboard generation, and transcription. Transcription has a standalone abstraction with Whisper/OpenAI and CTranslate2 implementations in `packages/transcription/src/`.

#### Federation, distribution, and storage
ActivityPub is a first-class protocol boundary: inbox/outbox HTTP controllers feed signed, validated activities into processors; outbound work is queued for delivery. Key paths are `server/core/controllers/activitypub/`, `server/core/lib/activitypub/process/`, and `server/core/lib/activitypub/send/`. Video distribution also includes WebTorrent support and tracker-facing endpoints (`server/core/lib/webtorrent.ts`, `server/core/controllers/tracker.ts`), plus redundancy between instances (`server/core/lib/redundancy.ts`). Files can reside on the local filesystem or object storage; object-storage URL/signing/proxy behavior is isolated in `server/core/lib/object-storage/`.

#### Client, player, and extension surfaces
The Angular SPA uses route-level feature areas for watching, publishing/managing videos, user libraries, and administration; app composition begins at `client/src/app/app.routes.ts`. Core client services centralize REST access, auth, routing, sockets, server configuration, and plugins in `client/src/app/core/`. Playback is independently built around Video.js and P2P/HLS plugins in `client/src/standalone/player/src/`, while embeddable-video bootstrapping and remote video/playlist retrieval reside in `client/src/standalone/videos/`. Server and client plugins are explicit extension boundaries, with server lifecycle/hooks in `server/core/lib/plugins/`, client hook rendering in `client/src/app/core/plugins/`, and shared plugin contracts in `packages/models/src/plugins/`.

#### Shared contracts and operations
`packages/models/src/` defines cross-process and API data contracts, including ActivityPub, video, runner, plugin, moderation, and token models; `packages/server-commands/src/` is the typed command layer consumed by the CLI. Runtime infrastructure includes Node.js/TypeScript, PostgreSQL via Sequelize models/migrations, Redis integration (`server/core/lib/redis.ts`), FFmpeg, WebTorrent/WebRTC delivery, Socket.IO-style notifications (`server/core/lib/peertube-socket.ts`), optional S3-compatible object storage, and Docker/Nginx production deployment assets in `support/docker/production/`.

Main entry points: [`apps/peertube-runner/src/peertube-runner.ts`](https://github.com/chocobozzz/peertube/blob/develop/apps/peertube-runner/src/peertube-runner.ts) (PeerTube runner), [`server/core/lib/job-queue/job-queue.ts`](https://github.com/chocobozzz/peertube/blob/develop/server/core/lib/job-queue/job-queue.ts) (Job queue), [`server/server.ts`](https://github.com/chocobozzz/peertube/blob/develop/server/server.ts) (Server entry), [`client/src/main.ts`](https://github.com/chocobozzz/peertube/blob/develop/client/src/main.ts) (Angular SPA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["PeerTube Server"]
  node_server_entry["Server entry<br/>Node.js entry<br/>[server.ts]"]
  node_initializers["Startup &amp; migrations<br/>initialization"]
  node_api["REST API controllers<br/>Express controllers"]
  node_middleware["Auth &amp; validation<br/>middleware"]
  node_models[("Domain models<br/>Sequelize models")]
  node_job_queue["Job queue<br/>async queue<br/>[job-queue.ts]"]
  node_job_handlers["Job handlers<br/>background handlers"]
  node_transcoding["Transcoding orchestration<br/>media dispatcher"]
  node_activitypub["ActivityPub pipeline<br/>federation"]
  node_activitypub_http["ActivityPub HTTP<br/>protocol controllers"]
  node_distribution["P2P &amp; redundancy<br/>video distribution<br/>[webtorrent.ts]"]
  node_object_storage["Object storage<br/>storage adapter"]
  node_server_plugins["Server plugins<br/>extension hooks"]
end

subgraph group_clients["Client &amp; Workers"]
  node_web_client["Angular SPA<br/>browser client<br/>[main.ts]"]
  node_client_core["Client core services<br/>SPA services"]
  node_player["Standalone player<br/>Video.js player"]
  node_runner["PeerTube runner<br/>remote worker<br/>[peertube-runner.ts]"]
  node_cli["PeerTube CLI<br/>automation executable<br/>[peertube.ts]"]
end

subgraph group_shared["Shared Services"]
  node_contracts["Shared models<br/>TypeScript contracts"]
  node_postgres[("PostgreSQL<br/>database")]
  node_redis[("Redis<br/>runtime integration<br/>[redis.ts]")]
  node_ffmpeg["FFmpeg package<br/>media processing"]
  node_transcription["Transcription package<br/>speech processing"]
end

node_server_entry -->|"boots"| node_initializers
node_initializers -->|"initializes"| node_models
node_models -->|"persists via Sequelize"| node_postgres
node_server_entry -->|"installs"| node_middleware
node_middleware -->|"guards requests to"| node_api
node_api -->|"reads and writes"| node_models
node_api -->|"enqueues expensive work"| node_job_queue
node_job_queue -->|"dispatches"| node_job_handlers
node_job_handlers -->|"orchestrates media work"| node_transcoding
node_transcoding -->|"uses"| node_ffmpeg
node_transcoding -.->|"offloads jobs to"| node_runner
node_runner -->|"executes media processing with"| node_ffmpeg
node_runner -->|"runs transcription via"| node_transcription
node_job_handlers -->|"moves and stores files"| node_object_storage
node_api -->|"serves distribution endpoints"| node_distribution
node_api -->|"exposes protocol endpoints"| node_activitypub_http
node_activitypub_http -->|"feeds validated activities"| node_activitypub
node_activitypub -->|"queues outbound delivery"| node_job_queue
node_activitypub -->|"updates federation state"| node_models
node_web_client -->|"composes"| node_client_core
node_client_core -->|"calls"| node_api
node_web_client -->|"embeds"| node_player
node_player -->|"uses P2P/HLS delivery"| node_distribution
node_cli -->|"automates"| node_api
node_api -.->|"uses API contracts"| node_contracts
node_runner -.->|"uses runner contracts"| node_contracts
node_server_plugins -.->|"implements plugin contracts"| node_contracts
node_api -.->|"uses runtime cache/integration"| node_redis

click node_server_entry "https://github.com/chocobozzz/peertube/blob/develop/server/server.ts"
click node_job_queue "https://github.com/chocobozzz/peertube/blob/develop/server/core/lib/job-queue/job-queue.ts"
click node_distribution "https://github.com/chocobozzz/peertube/blob/develop/server/core/lib/webtorrent.ts"
click node_web_client "https://github.com/chocobozzz/peertube/blob/develop/client/src/main.ts"
click node_runner "https://github.com/chocobozzz/peertube/blob/develop/apps/peertube-runner/src/peertube-runner.ts"
click node_cli "https://github.com/chocobozzz/peertube/blob/develop/apps/peertube-cli/src/peertube.ts"
click node_redis "https://github.com/chocobozzz/peertube/blob/develop/server/core/lib/redis.ts"

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_server_entry,node_initializers,node_api,node_middleware,node_models,node_job_queue,node_job_handlers,node_transcoding,node_activitypub,node_activitypub_http,node_distribution,node_object_storage,node_server_plugins toneBlue
class node_web_client,node_client_core,node_player,node_runner,node_cli toneAmber
class node_contracts,node_postgres,node_redis,node_ffmpeg,node_transcription toneMint
```

## Components

### PeerTube Server

Node.js API, media pipeline, and federation runtime.

- [Server entry](https://github.com/chocobozzz/peertube/blob/develop/server/server.ts): Node.js entry · `server/server.ts`
- **Startup & migrations**: initialization · Loads configuration, database state, and ordered migrations.
- **REST API controllers**: Express controllers · Video, user, search, admin, and runner endpoints.
- **Auth & validation**: middleware · Authorization, rate limits, ActivityPub checks, and input validation.
- **Domain models**: Sequelize models · Actors, videos, follows, jobs, runners, moderation, and statistics.
- [Job queue](https://github.com/chocobozzz/peertube/blob/develop/server/core/lib/job-queue/job-queue.ts): async queue · Runs imports, processing, delivery, storage, and notification work. · `server/core/lib/job-queue/job-queue.ts`
- **Job handlers**: background handlers
- **Transcoding orchestration**: media dispatcher · Selects local queued processing or remote runner work.
- **ActivityPub pipeline**: federation · Processes inbound activities and queues signed outbound delivery.
- **ActivityPub HTTP**: protocol controllers
- [P2P & redundancy](https://github.com/chocobozzz/peertube/blob/develop/server/core/lib/webtorrent.ts): video distribution · WebTorrent tracker integration and inter-instance redundancy. · `server/core/lib/webtorrent.ts`
- **Object storage**: storage adapter · S3-compatible URL, signing, and proxy behavior.
- **Server plugins**: extension hooks

### Client & Workers

Browser application, CLI, and remote execution runtime.

- [Angular SPA](https://github.com/chocobozzz/peertube/blob/develop/client/src/main.ts): browser client · Watching, publishing, libraries, and administration routes. · `client/src/main.ts`
- **Client core services**: SPA services · REST, auth, routing, sockets, configuration, and plugins.
- **Standalone player**: Video.js player · Playback with P2P and HLS plugins.
- [PeerTube runner](https://github.com/chocobozzz/peertube/blob/develop/apps/peertube-runner/src/peertube-runner.ts): remote worker · Registers with instances and processes media jobs through IPC. · `apps/peertube-runner/src/peertube-runner.ts`
- [PeerTube CLI](https://github.com/chocobozzz/peertube/blob/develop/apps/peertube-cli/src/peertube.ts): automation executable · `apps/peertube-cli/src/peertube.ts`

### Shared Services

Contracts and external runtime dependencies.

- **Shared models**: TypeScript contracts · API, ActivityPub, runner, moderation, token, and plugin contracts.
- **PostgreSQL**: database · Persistent storage accessed through Sequelize.
- [Redis](https://github.com/chocobozzz/peertube/blob/develop/server/core/lib/redis.ts): runtime integration · `server/core/lib/redis.ts`
- **FFmpeg package**: media processing
- **Transcription package**: speech processing · Whisper/OpenAI and CTranslate2 implementations.

## Connections

- Server entry → Startup & migrations: boots
- Startup & migrations → Domain models: initializes
- Domain models → PostgreSQL: persists via Sequelize
- Server entry → Auth & validation: installs
- Auth & validation → REST API controllers: guards requests to
- REST API controllers → Domain models: reads and writes
- REST API controllers → Job queue: enqueues expensive work
- Job queue → Job handlers: dispatches
- Job handlers → Transcoding orchestration: orchestrates media work
- Transcoding orchestration → FFmpeg package: uses
- Transcoding orchestration → PeerTube runner: offloads jobs to
- PeerTube runner → FFmpeg package: executes media processing with
- PeerTube runner → Transcription package: runs transcription via
- Job handlers → Object storage: moves and stores files
- REST API controllers → P2P & redundancy: serves distribution endpoints
- REST API controllers → ActivityPub HTTP: exposes protocol endpoints
- ActivityPub HTTP → ActivityPub pipeline: feeds validated activities
- ActivityPub pipeline → Job queue: queues outbound delivery
- ActivityPub pipeline → Domain models: updates federation state
- Angular SPA → Client core services: composes
- Client core services → REST API controllers: calls
- Angular SPA → Standalone player: embeds
- Standalone player → P2P & redundancy: uses P2P/HLS delivery
- PeerTube CLI → REST API controllers: automates
- REST API controllers → Shared models: uses API contracts
- PeerTube runner → Shared models: uses runner contracts
- Server plugins → Shared models: implements plugin contracts
- REST API controllers → Redis: uses runtime cache/integration
