VOD Documentation

VOD is a self-hosted video-on-demand platform. Admins upload videos through a resumable uploader; a background pipeline built on Celery and FFmpeg transcodes each file into an adaptive bitrate (ABR) HLS stream with up to seven quality levels; viewers browse and watch through a Next.js frontend with a custom video.js player. The backend is a FastAPI service with PostgreSQL, Redis and MinIO (S3-compatible object storage), fronted by Caddy and run with Docker Compose on a single small VPS.

Architecture diagram · placeholder

VOD at a glance: browser, Vercel frontend, Caddy, API, worker, Postgres, Redis, MinIO, tusd

One-screen system context diagram (C4 level 1/2) that every section links back to.

How these docs are organised

Each section covers one part of the system and stays inside it. Use the section switcher at the top of the sidebar.

Overview

What VOD is, the tech stack, local setup and a glossary of terms.

Architecture

High-level design, request routing and the upload-to-playback flow end to end.

Backend

The FastAPI service: auth, data model, video service, resumable uploads and the API.

Pipeline

The Celery + FFmpeg processing pipeline, its one-at-a-time queue and HLS output.

Frontend

The Next.js app: routing, data and auth, the player, uploads and the admin panel.

Infrastructure

Docker Compose, Caddy, local development and how production is deployed.

Operations

Deploy runbook, server setup, secrets, debugging commands and incident playbooks.

Decisions & Incidents

Architecture decision records and incident write-ups.

Roadmap

What is real today, what is not, and the improvement plan.

Interview Guide

A system-design walkthrough, trade-offs and likely questions.

How each page is written

Pages are built from the same parts, used where they fit:

Summary: what the part does, in a few lines.
Diagram: where a picture explains it faster.
How it works: numbered steps, with references to the source files.
Failure modes: what goes wrong and how the system reacts.
Trade-offs: why it was built this way and what that costs.

The Interview Guide collects the trade-offs across the whole system in one place.

Source of truth

Everything here was written from the code in the vod-app repository. File references such as backend/app/tasks/processing_queue.py point at that repository. If a page and the code disagree, the code wins, and the page should be fixed.