Architecture

🇩🇪 Deutsche Version

Overview

ITSWEBER Play ships as a single Docker container that exposes one port (3000). An Nginx instance inside the container multiplexes incoming requests and routes them to the appropriate internal service. There is no need for Docker Compose orchestration or a container network — everything runs in one process tree managed by s6-overlay.

Container Topology

┌─────────────────────────────────────────┐
│            itsweber-play:3000           │
│  ┌──────────────────────────────────┐   │
│  │         Nginx :80 (internal)     │   │
│  └──┬──────────────┬────────────────┘   │
│     │              │                    │
│  ┌──▼──┐       ┌───▼────┐              │
│  │ Web │       │  API   │              │
│  │:3100│       │ :4000  │              │
│  └─────┘       └───┬────┘              │
│                    │                   │
│  ┌─────┐  ┌──────┐ │  ┌──────┐        │
│  │Redis│  │MinIO │ │  │Pgsql │        │
│  │:6379│  │:9000 │ │  │:5432 │        │
│  └─────┘  └──────┘ │  └──────┘        │
│                ┌───▼────┐             │
│                │ Worker │             │
│                └────────┘             │
└─────────────────────────────────────────┘

All inter-service communication uses 127.0.0.1. The Web frontend is a Next.js 15 App Router application. The API is a Fastify server exposing tRPC procedures and Better Auth endpoints. The Worker is a BullMQ consumer that runs FFmpeg and yt-dlp jobs.

s6-overlay Init Order

s6-overlay manages the startup sequence and restarts any crashed service automatically:

1. postgres-init — Creates the Postgres data directory and cluster if it does not exist.
2. postgres — Starts the Postgres server on :5432.
3. migrate — Runs prisma migrate deploy against the local Postgres instance. Blocks until complete.
4. minio — Starts the MinIO server on :9000 and creates default buckets.
5. redis — Starts the Redis server on :6379.
6. api — Starts the Fastify API server on :4000.
7. worker — Starts the BullMQ worker process.
8. web — Starts the Next.js server on :3100.
9. nginx — Starts Nginx on :80 (internal), which is mapped to the container's exposed port 3000.

Services

Data Flows

Upload

Browser → Web (tus chunk) → API → MinIO (raw)
                                → Worker (enqueue)
Worker → MinIO (pull raw) → FFmpeg → HLS segments → MinIO (play-videos/)
Worker → Redis pub/sub (progress events)
API → SSE → Browser (live progress bar)

External Import (yt-dlp)

1. User submits a URL in Studio.
2. API creates a Video record with status=importing, enqueues a job.
3. Worker runs yt-dlp to download the source, then transcodes with FFmpeg.
4. Video becomes visible. Default visibility is private — the user must explicitly publish it.

Auth

Browser → POST /auth/sign-in → Better Auth → session cookie (HTTP-only, SameSite=Lax)
Browser → GET /trpc/* → API reads cookie → validates session → returns data

Theme Update

Admin saves token change → API writes to DB → SSE event broadcast
Browser receives SSE → replaces <style id="theme-vars"> → live update, no reload

Storage Layout

MinIO organizes data into the following buckets:

All buckets are private. The API generates pre-signed URLs for playback and asset delivery.

Monorepo Packages