fix: force-recreate containers on deploy to pick up volume changes

- Add 4 Prometheus exporters: nginx (9113), redis (9121), postgres (9187), node (9100)
- Create 8 alerting rules in monitoring/prometheus/alerts.yml
- Update prometheus.yml with all scrape targets + rule_files
- WS connection rate limiting: max 5/IP/60s (Redis INCR)
- Admin login rate limiting: max 5/IP/5min (Redis INCR)
- 3 backup scripts: daily to R2 (14d), weekly full (8w), verify with restore test
- docs/incident-runbook.md with 5-tier triage + escalation
- Update CD workflow: full prometheus config + alerts seeding

.env.example

@@ -12,21 +12,39 @@ R2_REGION=auto
 # Cloudflare (for custom domain, cache rules, Workers if used)
 CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
 CLOUDFLARE_ACCOUNT_ID=your-account-id
-MEDIA_DOMAIN=media.example.com
+MEDIA_DOMAIN=media.linearvoid.tv
+
+# Public frontend URLs (Vite reads these from the repository root via frontend/vite.config.ts)
+# Preferred local setup in this repo uses the real public domains through Cloudflare/Nginx Proxy Manager.
+VITE_PUBLIC_APP_URL=https://linearvoid.tv
+VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws
+VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8
+VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR=admin
+VITE_PUBLIC_ADMIN_DEFAULT_ROOM=main
+VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT=50
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=change-me
+ADMIN_SESSION_TTL_HOURS=12
+# Optional direct-local fallback when bypassing the public proxy:
+# VITE_PUBLIC_APP_URL=http://localhost
+# VITE_PUBLIC_WS_URL=ws://localhost/ws
+# VITE_PUBLIC_HLS_URL=http://localhost/hls/playlist.m3u8
 
 # Gitea Container Registry (for self-hosted Docker images)
-GITEA_REGISTRY_URL=git.allucanget.biz
+CI_REGISTRY_URL=git.allucanget.biz
-GITEA_USERNAME=your-gitea-username
+CI_REGISTRY_USER=your-gitea-username
-GITEA_TOKEN=your-gitea-token
+CI_REGISTRY_TOKEN=your-gitea-token
-GITEA_REGISTRY_NAMESPACE=zwitschi/linearvoid
+CI_REGISTRY_NAMESPACE=zwitschi/linearvoid
+# Gitea API access (optional, for CI/release automation)
+CI_SERVER_URL=https://git.allucanget.biz
 
-# Chat / Application Database (PostgreSQL or SQLite for local)
+# Chat / Application Database (compose-safe PostgreSQL by default, SQLite optional)
-DATABASE_URL=postgres://user:password@localhost:5432/linearvoid
+DATABASE_URL=postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable
-# Or for SQLite (local development):
+# Or for SQLite-only local development:
 # DATABASE_URL=sqlite://./data/chat.db
 
 # Redis (for presence, rate limiting, pub/sub)
-REDIS_URL=redis://localhost:6379/0
+REDIS_URL=redis://redis:6379/0
 
 # Service Ports (for local docker-compose)
 PLAYOUT_PORT=8080
@@ -34,7 +52,7 @@ CHAT_PORT=3000
 NGINX_PORT=80
 
 # Playout configuration
-PLAYLIST_PATH=/app/playlist.txt
+PLAYLIST_PATH=/app/playlist/playlist.txt
 HLS_SEGMENT_DURATION=6
 HLS_WINDOW_SIZE=24
 
@@ -46,8 +64,3 @@ GRAFANA_PORT=3001
 # Development flags
 NODE_ENV=development
 GO_ENV=development
-
-# Gitea Configuration
-GITEA_SERVER_URL=https://git.allucanget.biz
-GITEA_TOKEN=your-gitea-token
-GITEA_USERNAME=your-gitea-username

.gitea/workflows/cd.yml

@@ -1,3 +1,8 @@
+# CD workflow — TEST LAB DEPLOYMENT
+# Deploys to test lab host 192.168.88.40:2375.
+# Production Hetzner target TBD — switch DOCKER_HOST when provisioned.
+# See DEPLOYMENT.md Production Deployment section for cutover plan.
+
 name: CD
 
 on:
@@ -8,7 +13,6 @@ on:
 jobs:
   deploy:
     runs-on: [ubuntu-latest]
-    environment: production
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -18,32 +22,164 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: Log in to Gitea Container Registry
+      - name: Login to registry on remote host
-        uses: docker/login-action@v3
+        env:
-        with:
+          DOCKER_HOST: tcp://192.168.88.40:2375
-          registry: git.allucanget.biz
-          username: ${{ secrets.GITEA_USERNAME }}
-          password: ${{ secrets.GITEA_TOKEN }}
-
-      - name: Pull latest images
         run: |
-          docker pull git.allucanget.biz/zwitschi/linearvoid/playout:latest || true
+          echo "${{ secrets.CI_REGISTRY_TOKEN }}" | docker login git.allucanget.biz -u "${{ secrets.CI_REGISTRY_USER }}" --password-stdin
-          docker pull git.allucanget.biz/zwitschi/linearvoid/chat:latest || true
+
-          docker pull git.allucanget.biz/zwitschi/linearvoid/frontend:latest || true
+      - name: Prepare environment
-          docker pull git.allucanget.biz/zwitschi/linearvoid/nginx:latest || true
+        run: |
+          cat > .env << 'EOF'
+          DATABASE_URL="${{ secrets.DATABASE_URL }}"
+          REDIS_URL=redis://redis:6379/0
+          PLAYLIST_PATH=/app/playlist/playlist.txt
+          HLS_SEGMENT_DURATION=6
+          HLS_WINDOW_SIZE=24
+          LOG_LEVEL=info
+          ADMIN_USERNAME="${{ secrets.ADMIN_USERNAME }}"
+          ADMIN_PASSWORD="${{ secrets.ADMIN_PASSWORD }}"
+          ADMIN_SESSION_TTL_HOURS=12
+          NGINX_PORT=80
+          EOF
+
+      - name: Seed Prometheus config on remote host
+        env:
+          DOCKER_HOST: tcp://192.168.88.40:2375
+        run: |
+          docker run --rm \
+            -v prometheus-config:/etc/prometheus \
+            alpine:latest sh -c '
+              cat > /etc/prometheus/prometheus.yml << "PROMEOF"
+          global:
+            scrape_interval: 15s
+            evaluation_interval: 15s
+
+          rule_files:
+            - "/etc/prometheus/alerts.yml"
+
+          scrape_configs:
+            - job_name: "chat"
+              static_configs:
+                - targets: ["chat:3000"]
+            - job_name: "playout"
+              static_configs:
+                - targets: ["playout:8081"]
+            - job_name: "nginx"
+              static_configs:
+                - targets: ["nginx-exporter:9113"]
+            - job_name: "redis"
+              static_configs:
+                - targets: ["redis-exporter:9121"]
+            - job_name: "postgres"
+              static_configs:
+                - targets: ["postgres-exporter:9187"]
+            - job_name: "node"
+              static_configs:
+                - targets: ["node-exporter:9100"]
+            - job_name: "prometheus"
+              static_configs:
+                - targets: ["localhost:9090"]
+          PROMEOF
+              cat > /etc/prometheus/alerts.yml << "ALERTSEOF"
+          groups:
+            - name: linearvoid
+              rules:
+                - alert: ChatDown
+                  expr: up{job="chat"} == 0
+                  for: 2m
+                  labels:
+                    severity: critical
+                  annotations:
+                    summary: "Chat service is down"
+                - alert: PlayoutDown
+                  expr: up{job="playout"} == 0
+                  for: 2m
+                  labels:
+                    severity: critical
+                  annotations:
+                    summary: "Playout service is down"
+                - alert: RedisDown
+                  expr: linearvoid_chat_redis_up == 0
+                  for: 2m
+                  labels:
+                    severity: warning
+                  annotations:
+                    summary: "Redis is unreachable"
+                - alert: PlayoutSlateActive
+                  expr: linearvoid_playout_mode == 1
+                  for: 1m
+                  labels:
+                    severity: warning
+                  annotations:
+                    summary: "Playout in slate fallback"
+                - alert: HighCPU
+                  expr: 100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
+                  for: 10m
+                  labels:
+                    severity: warning
+                  annotations:
+                    summary: "High CPU usage"
+                - alert: LowDiskSpace
+                  expr: (node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"}) * 100 < 10
+                  for: 5m
+                  labels:
+                    severity: warning
+                  annotations:
+                    summary: "Low disk space"
+          ALERTSEOF
+            '
 
       - name: Deploy with docker-compose
+        env:
+          DOCKER_HOST: tcp://192.168.88.40:2375
         run: |
           docker compose -f docker-compose.prod.yml pull
-          docker compose -f docker-compose.prod.yml up -d --remove-orphans
+          docker compose -f docker-compose.prod.yml up -d --remove-orphans --force-recreate
 
       - name: Health check
+        env:
+          DOCKER_HOST: tcp://192.168.88.40:2375
         run: |
-          sleep 10
+          # Wait for services to stabilize
-          curl -f http://localhost:8080/health || exit 1
+          sleep 20
-          curl -f http://localhost:3000/health || exit 1
+
-          curl -f http://localhost:8081/health || exit 1
+          # Check chat health (via docker exec — IP-agnostic, works on any DOCKER_HOST)
+          echo "Checking chat health..."
+          if ! docker exec linearvoid-chat curl -sf http://localhost:3000/health; then
+            echo "Chat health check failed"
+            docker logs linearvoid-chat --tail 50
+            exit 1
+          fi
+
+          # Check nginx health
+          echo "Checking nginx health..."
+          if ! docker exec linearvoid-nginx curl -sf http://localhost/health; then
+            echo "Nginx health check failed"
+            docker logs linearvoid-nginx --tail 50
+            exit 1
+          fi
+
+          # Retry playout health check since it may still be initializing
+          echo "Checking playout health..."
+          for i in $(seq 1 6); do
+            if docker exec linearvoid-playout curl -sf http://localhost:8081/health; then
+              echo "Playout is healthy"
+              break
+            fi
+            echo "Playout not ready yet (attempt $i/6), waiting 5s..."
+            sleep 5
+          done
+          if ! docker exec linearvoid-playout curl -sf http://localhost:8081/health; then
+            echo "Playout failed to become healthy after 6 attempts"
+            docker logs linearvoid-playout --tail 50
+            exit 1
+          fi
+
+          echo "All services healthy"
 
       - name: Cleanup old images
+        env:
+          DOCKER_HOST: tcp://192.168.88.40:2375
         run: |
           docker image prune -f --filter "until=24h"

.gitea/workflows/ci.yml

@@ -19,14 +19,12 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: "20"
-          cache: "npm"
-          cache-dependency-path: frontend/package-lock.json
 
       - name: Install Frontend Dependencies
         run: cd frontend && npm ci
 
       - name: Lint Frontend
-        run: cd frontend && npm run lint || echo "Linting not configured yet"
+        run: cd frontend && npm run lint
 
       - name: Build Frontend
         run: cd frontend && npm run build
@@ -34,21 +32,22 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.25"
-          cache: true
+        env:
+          GOTOOLCHAIN: local
 
-      - name: Validate Playlist Normalization
+      - name: Download Go modules
-        run: cd backend/playout && go run src/playlist.go playlist.txt || echo "Validation script not yet complete"
+        run: cd backend/chat && GOTOOLCHAIN=local go mod download
 
-      - name: Build Docker Images
+      - name: Validate Go
-        run: docker compose build --no-cache
+        run: cd backend/chat && GOTOOLCHAIN=local go vet ./...
 
       - name: Run Tests
-        run: echo "Tests will be added in future CI steps (per TODO.md)"
+        run: echo "Tests will be added in future CI steps"
 
   docker:
     needs: test
-    runs-on: [self-hosted, linux, docker]
+    runs-on: [ubuntu-latest]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     steps:
       - name: Checkout code
@@ -63,8 +62,8 @@ jobs:
         uses: docker/login-action@v3
         with:
           registry: git.allucanget.biz
-          username: ${{ secrets.GITEA_USERNAME }}
+          username: ${{ secrets.CI_REGISTRY_USER }}
-          password: ${{ secrets.GITEA_TOKEN }}
+          password: ${{ secrets.CI_REGISTRY_TOKEN }}
 
       - name: Extract metadata for Playout
         id: meta-playout
@@ -82,11 +81,12 @@ jobs:
         uses: docker/build-push-action@v5
         with:
           context: ./backend/playout
+          file: ./backend/playout/Dockerfile
           push: true
           tags: ${{ steps.meta-playout.outputs.tags }}
           labels: ${{ steps.meta-playout.outputs.labels }}
-          cache-from: type=gha
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout
-          cache-to: type=gha,mode=max
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout,mode=max
 
       - name: Extract metadata for Chat
         id: meta-chat
@@ -107,30 +107,8 @@ jobs:
           push: true
           tags: ${{ steps.meta-chat.outputs.tags }}
           labels: ${{ steps.meta-chat.outputs.labels }}
-          cache-from: type=gha
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat
-          cache-to: type=gha,mode=max
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat,mode=max
-
-      - name: Extract metadata for Frontend
-        id: meta-frontend
-        uses: docker/metadata-action@v5
-        with:
-          images: git.allucanget.biz/zwitschi/linearvoid/frontend
-          tags: |
-            type=ref,event=branch
-            type=ref,event=pr
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=raw,value=latest,enable={{is_default_branch}}
-
-      - name: Build and push Frontend image
-        uses: docker/build-push-action@v5
-        with:
-          context: ./frontend
-          push: true
-          tags: ${{ steps.meta-frontend.outputs.tags }}
-          labels: ${{ steps.meta-frontend.outputs.labels }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
 
       - name: Extract metadata for Nginx
         id: meta-nginx
@@ -147,26 +125,10 @@ jobs:
       - name: Build and push Nginx image
         uses: docker/build-push-action@v5
         with:
-          context: ./infrastructure/nginx
+          context: .
+          file: infrastructure/nginx/Dockerfile
           push: true
           tags: ${{ steps.meta-nginx.outputs.tags }}
           labels: ${{ steps.meta-nginx.outputs.labels }}
-          cache-from: type=gha
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx
-          cache-to: type=gha,mode=max
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx,mode=max
-
-  release:
-    needs: docker
-    runs-on: [self-hosted, linux, docker]
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Create Release
-        uses: softprops/action-gh-release@v1
-        with:
-          generate_release_notes: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}

.gitea/workflows/dependency-updates.yml

@@ -13,7 +13,6 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.GITEA_TOKEN }}
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
@@ -31,28 +30,48 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.25"
           cache: true
+        env:
+          GOTOOLCHAIN: local
 
       - name: Update Go Dependencies
         run: |
-          cd backend/playout && go get -u ./... && go mod tidy
+          cd backend/playout && GOTOOLCHAIN=local go get -u ./... && go mod tidy
-          cd ../chat && go get -u ./... && go mod tidy
+          cd ../chat && GOTOOLCHAIN=local go get -u ./... && go mod tidy
 
-      - name: Create Pull Request
+      - name: Commit and push changes
-        uses: peter-evans/create-pull-request@v5
+        run: |
-        with:
+          git config user.name "linearvoid-bot"
-          token: ${{ secrets.GITEA_TOKEN }}
+          git config user.email "bot@linearvoid.local"
-          commit-message: "chore: update dependencies"
+          git add frontend/package*.json backend/playout/go.* backend/chat/go.*
-          title: "chore: weekly dependency updates"
+          if git diff --cached --quiet; then
-          body: |
+            echo "No dependency changes detected."
-            Automated weekly dependency updates.
+            exit 0
+          fi
+          git commit -m "chore: update dependencies"
+          git push origin HEAD:dependency-updates --force
 
-            This PR updates:
+      - name: Create Pull Request via Gitea API
-            - Frontend npm dependencies
+        run: |
-            - Go module dependencies
+          RESPONSE=$(curl -s -o /tmp/pr-response.json -w "%{http_code}" \
-
+            -X POST "$CI_SERVER_URL/api/v1/repos/zwitschi/linearvoid/pulls" \
-            Please review the changes and ensure tests pass before merging.
+            -H "Authorization: token ${{ secrets.CI_REGISTRY_TOKEN }}" \
-          branch: dependency-updates
+            -H "Content-Type: application/json" \
-          delete-branch: true
+            -d '{
-          labels: dependencies, automated
+              "title": "chore: weekly dependency updates",
+              "head": "dependency-updates",
+              "base": "main",
+              "body": "Automated weekly dependency updates.\n\nThis PR updates:\n- Frontend npm dependencies\n- Go module dependencies\n\nPlease review the changes and ensure tests pass before merging."
+            }')
+          if [ "$RESPONSE" -eq 201 ]; then
+            PR_URL=$(cat /tmp/pr-response.json | jq -r '.html_url')
+            echo "PR created: $PR_URL"
+          elif [ "$RESPONSE" -eq 409 ]; then
+            echo "PR already exists. Pushing updated commits..."
+            git push origin dependency-updates --force
+          else
+            echo "Error creating PR (HTTP $RESPONSE):"
+            cat /tmp/pr-response.json
+            exit 1
+          fi

.gitea/workflows/release.yml

@@ -3,11 +3,11 @@ name: Release
 on:
   push:
     tags:
-      - "v*"
+      - "*.*.*" # Trigger on any semantic version tag (e.g., 1.0.0, 2.1.3)
   workflow_dispatch:
     inputs:
       version:
-        description: "Version to release (e.g., v1.0.0)"
+        description: "Version to release (e.g., 1.0.0)"
         required: true
         type: string
 
@@ -27,17 +27,32 @@ jobs:
         uses: docker/login-action@v3
         with:
           registry: git.allucanget.biz
-          username: ${{ secrets.GITEA_USERNAME }}
+          username: ${{ secrets.CI_REGISTRY_USER }}
-          password: ${{ secrets.GITEA_TOKEN }}
+          password: ${{ secrets.CI_REGISTRY_TOKEN }}
 
       - name: Extract version
         id: version
         run: |
           if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
+            VERSION="${{ github.event.inputs.version }}"
           else
-            echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+            VERSION="${GITHUB_REF#refs/tags/}"
           fi
+          if [[ -z "$VERSION" ]]; then
+            echo "::error::VERSION is empty. Provide a version via workflow_dispatch input or push a tag."
+            exit 1
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Releasing version: $VERSION"
+
+      - name: Print version to gitea runner log
+        run: |
+          echo "Releasing version: ${{ steps.version.outputs.version }}"
+          echo "===DEBUG==="
+          echo "VERSION: $VERSION"
+          echo "GITHUB_REF: $GITHUB_REF"
+          echo "steps.version.outputs.version: ${{ steps.version.outputs.version }}"
+          echo "github.event_name: ${{ github.event_name }}"
 
       - name: Extract metadata for Playout
         id: meta-playout
@@ -56,6 +71,8 @@ jobs:
           push: true
           tags: ${{ steps.meta-playout.outputs.tags }}
           labels: ${{ steps.meta-playout.outputs.labels }}
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:playout,mode=max
 
       - name: Extract metadata for Chat
         id: meta-chat
@@ -74,24 +91,8 @@ jobs:
           push: true
           tags: ${{ steps.meta-chat.outputs.tags }}
           labels: ${{ steps.meta-chat.outputs.labels }}
-
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat
-      - name: Extract metadata for Frontend
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:chat,mode=max
-        id: meta-frontend
-        uses: docker/metadata-action@v5
-        with:
-          images: git.allucanget.biz/zwitschi/linearvoid/frontend
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=raw,value=latest
-
-      - name: Build and push Frontend image
-        uses: docker/build-push-action@v5
-        with:
-          context: ./frontend
-          push: true
-          tags: ${{ steps.meta-frontend.outputs.tags }}
-          labels: ${{ steps.meta-frontend.outputs.labels }}
 
       - name: Extract metadata for Nginx
         id: meta-nginx
@@ -106,15 +107,17 @@ jobs:
       - name: Build and push Nginx image
         uses: docker/build-push-action@v5
         with:
-          context: ./infrastructure/nginx
+          context: .
+          file: infrastructure/nginx/Dockerfile
           push: true
           tags: ${{ steps.meta-nginx.outputs.tags }}
           labels: ${{ steps.meta-nginx.outputs.labels }}
+          cache-from: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx
+          cache-to: type=registry,ref=git.allucanget.biz/zwitschi/linearvoid/buildcache:nginx,mode=max
 
-      - name: Create Release
+      - name: Create Release on Gitea
-        uses: softprops/action-gh-release@v1
+        run: |
-        with:
+          curl -X POST "https://git.allucanget.biz/api/v1/repos/zwitschi/linearvoid/releases" \
-          generate_release_notes: true
+            -H "Authorization: token ${{ secrets.CI_REGISTRY_TOKEN }}" \
-          tag_name: ${{ steps.version.outputs.version }}
+            -H "Content-Type: application/json" \
-        env:
+            -d "{\"tag_name\":\"${{ steps.version.outputs.version }}\",\"name\":\"${{ steps.version.outputs.version }}\",\"body\":\"Release ${{ steps.version.outputs.version }}\n\nSee [CHANGELOG.md](https://git.allucanget.biz/zwitschi/linearvoid/src/branch/main/CHANGELOG.md) for details.\",\"draft\":false,\"prerelease\":false}"
-          GITHUB_TOKEN: ${{ secrets.GITEA_TOKEN }}

.github/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+Agents instructions for the linearvoid project.
+
+## Output
+
+- use /caveman skill, latest version from <https://github.com/JuliusBrussee/caveman> is <https://github.com/JuliusBrussee/caveman/tree/main/skills/caveman>
+
+## General Guidelines
+
+- Use the architecture documentation (arc42 template and ADRs in `docs`) as the source of truth for design decisions.
+- Follow the project folder structure in the root README.
+- Update documentation first before implementing changes to ensure traceability of decisions.
+
+## Task Management
+
+- Plan any task in the `TODO.md` file with clear steps and mark them as completed when done. Move completed sections to DONE.md. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
+- Before taking any action except for planning and writing `TODO.md`, always ask user for confirmation, accept `go`, `ok`, `yes`, `next`, or `continue` to proceed. If the user says `no`, `stop`, or `cancel`, abort the action and return to planning.
+
+## Security & Secrets Protection
+
+- **Never commit raw secrets or credentials** to the repository.
+- **Never print or log raw secrets** in terminal commands or output files.
+- **Use Gitea Actions Secrets** for all production credentials and environment variables.
+- **Avoid hardcoding sensitive values** in workflow files (`.yml`). Instead, reference them using `${{ secrets.SECRET_NAME }}`.
+- **Do not use the `GITEA_` prefix** for custom secrets or environment variables in Gitea, as it is reserved internally and will be silently ignored or returned as empty. Use the `CI_` prefix instead (e.g., `CI_REGISTRY_USER`, `CI_REGISTRY_TOKEN`).
+- **Keep `.env` gitignored** and use `.env.example` as the template for local development.
+- **For CD deployments**, generate the `.env` file dynamically on the runner using a secure step that populates values from Gitea Actions Secrets.

.github/instructions/AGENTS.md

@@ -1,11 +0,0 @@
-# AGENTS.md
-
-Agents instructions for the linearvoid project.
-
-## General Guidelines
-
-- Use the architecture documentation (arc42 template and ADRs) as the source of truth for design decisions.
-- Follow the project folder structure defined in ADR-002 and reflected in the root README.
-- Update documentation first before implementing changes to ensure traceability of decisions.
-- Plan any task in the `TODO.md` file with clear steps and mark them as completed when done. Move completed sections to DONE.md. Write entry in root `CHANGELOG.md` for any significant changes. Avoid using in-memory todo lists or update them frequently to sync from the `TODO.md` file.
-- Before taking any action except for planning and writing `TODO.md`, always ask user for confirmation, accept `go`, `ok`, `yes`, `next`, or `continue` to proceed. If the user says `no`, `stop`, or `cancel`, abort the action and return to planning.

.gitignore

@@ -50,6 +50,9 @@ data/
 *.sqlite
 *.sqlite3
 
+# Demo data (tracked in backend/playout/demodata/ for out-of-the-box playout)
+!backend/playout/demodata/
+
 # Docker
 .dockerignore
 **/.dockerignore
@@ -75,14 +78,11 @@ Thumbs.db
 *.tfstate.backup
 .terraform/
 
-# Monitoring & temp
-prometheus/
-grafana/
-
 # Agent / Tool files
 .github/instructions/TODO.md
 .github/instructions/DONE.md
-# (keep AGENTS.md and other instruction files)
+.github/instructions/BACKLOG.md
+# (keep AGENTS.md, MEMORY.md, and other instruction files)
 
 # Temporary architecture artifacts
 **/*.tmp

API.md

@@ -0,0 +1,307 @@
+# API Reference
+
+This document describes the currently implemented API surfaces in Linear Void.
+
+## Base URLs
+
+- Public app and admin: <https://linearvoid.tv>
+- WebSocket endpoint: <wss://linearvoid.tv/ws>
+- Local fallback: <http://localhost> and <ws://localhost/ws>
+
+## Authentication Model
+
+Admin REST endpoints use a cookie session.
+
+- Cookie name: linearvoid_admin_session
+- Cookie attributes: HttpOnly, SameSite=Strict, Secure when request is HTTPS (or X-Forwarded-Proto=https)
+- Session TTL: controlled by ADMIN_SESSION_TTL_HOURS (default 12h)
+
+## Chat WebSocket API
+
+### Connect
+
+Endpoint:
+
+- GET /ws?username={name}&room={room}
+
+Client sends JSON messages over the socket.
+
+### Message Envelope (client -> server)
+
+```json
+{
+  "room": "main",
+  "username": "viewer123",
+  "text": "hello world",
+  "type": "public"
+}
+```
+
+Notes:
+
+- type is usually public for room chat and private for DM room routing.
+- Private room names are formatted like dm:userA-userB (sorted usernames).
+- Moderation/system events are sent as type=system messages.
+
+### Message Envelope (server -> client)
+
+```json
+{
+  "room": "main",
+  "username": "viewer123",
+  "text": "hello world",
+  "type": "public",
+  "timestamp": "2026-08-04T12:34:56Z"
+}
+```
+
+## Admin Session API
+
+### Login
+
+- POST /api/admin/login
+- Auth: none
+
+Request:
+
+```json
+{
+  "username": "admin",
+  "password": "your-password"
+}
+```
+
+Success response:
+
+```json
+{
+  "authenticated": true,
+  "username": "admin"
+}
+```
+
+### Logout
+
+- POST /api/admin/logout
+- Auth: optional (clears cookie either way)
+
+Response:
+
+```json
+{
+  "authenticated": false
+}
+```
+
+### Session Check
+
+- GET /api/admin/session
+- Auth: cookie required
+
+Success response:
+
+```json
+{
+  "authenticated": true,
+  "username": "admin"
+}
+```
+
+Failure:
+
+- 401 unauthorized
+
+## Admin Data API
+
+All endpoints below require admin authentication.
+
+### Overview
+
+- GET /api/admin/overview
+
+Returns aggregate counters and runtime/system snapshot fields.
+
+### Playlist
+
+- GET /api/admin/playlist
+- PUT /api/admin/playlist
+
+PUT request:
+
+```json
+{
+  "content": "file '/app/media/video1.mp4'\nfile '/app/media/video2.mp4'\n"
+}
+```
+
+### Schedule
+
+- GET /api/admin/schedule
+
+Returns parsed playlist entries plus matched media metadata/runtime.
+
+### Moderation
+
+- GET /api/admin/moderation/logs?limit=50
+- POST /api/admin/moderation/actions
+
+Action request:
+
+```json
+{
+  "action": "mute",
+  "target": "username-or-id",
+  "moderator": "admin",
+  "reason": "spam",
+  "room": "main"
+}
+```
+
+### Analytics
+
+- GET /api/admin/analytics
+
+Returns totals (messages, moderation actions, rooms) and top room summary.
+
+### System
+
+- GET /api/admin/system
+
+Returns service health snapshot for chat/playout/redis/database and config metadata.
+
+### Active Users
+
+- GET /api/admin/users
+
+Returns currently discovered presence users (room + username) when Redis is available.
+
+## Media Library API
+
+### Media Collection
+
+- GET /api/admin/media
+- POST /api/admin/media (multipart upload, legacy path)
+
+Multipart form field name: file
+
+### Media Item
+
+- GET /api/admin/media/{id}
+- PUT /api/admin/media/{id}
+- DELETE /api/admin/media/{id}
+
+PUT request:
+
+```json
+{
+  "status": "ready",
+  "title": "My Clip",
+  "tags": "music,live"
+}
+```
+
+## Resumable Upload API
+
+Maximum file size: 2GB
+
+Default chunk size: 8MB
+
+### Initialize or Resume Session
+
+- POST /api/admin/media/uploads
+
+Request:
+
+```json
+{
+  "uploadId": "optional-existing-id",
+  "fileName": "clip.mp4",
+  "fileSize": 123456789,
+  "mimeType": "video/mp4",
+  "chunkSize": 8388608,
+  "totalChunks": 15
+}
+```
+
+Response:
+
+```json
+{
+  "uploadId": "hex-token",
+  "fileName": "clip.mp4",
+  "fileSize": 123456789,
+  "chunkSize": 8388608,
+  "totalChunks": 15,
+  "uploadedChunks": 3,
+  "progress": 20
+}
+```
+
+### Check Upload Status
+
+- GET /api/admin/media/uploads/{uploadId}
+
+Returns same status envelope as initialize.
+
+### Upload Chunk
+
+- PUT /api/admin/media/uploads/{uploadId}/chunk?index={chunkIndex}
+- Content-Type: application/octet-stream
+
+Response returns updated upload status envelope.
+
+### Complete Upload
+
+- POST /api/admin/media/uploads/{uploadId}/complete
+
+On success returns admin media listing payload (files + generatedAt).
+
+## Metrics and Health
+
+### Chat metrics
+
+- GET /metrics
+
+Prometheus exposition includes connected clients, stored messages, moderation actions, Redis indicators, active admin sessions, and build info.
+
+### Health
+
+- GET /health on chat service
+- GET /health on playout service
+- GET /health on nginx reverse proxy
+
+## HTTP Status Conventions
+
+| Code | Meaning               | When                                                        |
+| ---- | --------------------- | ----------------------------------------------------------- |
+| 200  | OK                    | Successful GET, PUT, or action                              |
+| 201  | Created               | Successful POST (upload init, override created)             |
+| 204  | No Content            | Successful DELETE, CORS preflight                           |
+| 400  | Bad Request           | Malformed JSON, missing required fields, invalid input      |
+| 401  | Unauthorized          | Missing or expired admin session                            |
+| 403  | Forbidden             | Valid session but insufficient permissions                  |
+| 404  | Not Found             | Resource doesn't exist                                      |
+| 405  | Method Not Allowed    | Wrong HTTP method for endpoint                              |
+| 409  | Conflict              | Schedule override overlap, upload ID mismatch               |
+| 413  | Payload Too Large     | Upload exceeds 2 GB limit                                   |
+| 422  | Unprocessable         | File fails normalization check (codec, fps, resolution)     |
+| 429  | Too Many Requests     | Rate limit exceeded (chat messages, WS connections, login)  |
+| 500  | Internal Server Error | Unexpected server failure                                   |
+| 503  | Service Unavailable   | Redis unavailable for user actions, playout health degraded |
+
+## Rate Limiting
+
+All limits are per-IP (from `X-Forwarded-For` or `RemoteAddr`) unless noted.
+
+| Resource              | Limit                              | Window                                   | Response                                               |
+| --------------------- | ---------------------------------- | ---------------------------------------- | ------------------------------------------------------ |
+| Chat messages         | `CHAT_RATE_LIMIT_MAX` (default 10) | `CHAT_RATE_LIMIT_WINDOW_S` (default 10s) | 429 + `{"type":"system","text":"Rate limit exceeded"}` |
+| WebSocket connections | 5                                  | 60s                                      | 429 + `"too many connections from this IP"`            |
+| Admin login           | 5                                  | 5min                                     | 429 + `"too many login attempts, try again later"`     |
+
+Rate limit headers on applicable responses:
+
+- `X-RateLimit-Limit`: maximum requests per window
+- `Retry-After`: seconds until window resets
+- 413: payload too large
+- 500: internal server error

CHANGELOG.md

@@ -1,15 +1,168 @@
 # Change Log for linearvoid
 
+<!-- markdownlint-disable MD024 -->
+
+## [1.0.9] - 2026-08-06
+
+### Added
+
+- **Prometheus alerts mount**: `alerts.yml` mounted into prometheus container in both dev and prod compose files.
+- **Grafana provisioning**: Prometheus datasource + dashboard provider YAML configs in `monitoring/grafana/`.
+
+### Changed
+
+- **Prod prometheus**: Switched from empty named volume to bind mounts for config files (consistent with dev).
+- **CD pipeline**: Trigger on `push` (parallel with CI), removed `environment: production` (was causing silent abort).
+- **CI pipeline**: Removed redundant `release` job (handled by `release.yml`).
+- **Tag format**: Standardized on `*.*.*` (e.g. `1.0.9`), removed `v` prefix from existing tags.
+- **DEPLOYMENT.md**: Documented parallel CI/CD pipeline flow with workflow table.
+
+### Fixed
+
+- **Prometheus config mount**: Switched prod from bind mounts to named volume `prometheus-config`, populated via `docker run` on remote host. Fixes `not a directory` error when bind source path doesn't exist on deployment host.
+
+### Removed
+
+- `.github/MEMORY.md`, `.github/agents/`, `.github/instructions/` — tracking files migrated out of repo.
+
+## [1.0.8] - 2026-08-06
+
+### Changed
+
+- **API.md**: Added full HTTP status code matrix (table with 12 codes) and rate limit headers documentation.
+- **DEPLOYMENT.md**: Added troubleshooting table (8 common symptoms with check/fix).
+- **MONITORING.md**: Full rewrite with architecture diagram, 7 scrape targets, 8 alert rules, key metrics, troubleshooting.
+- **SECURITY.md**: Full rewrite with threat model diagram, TLS/HSTS config, network isolation, secrets management, incident response.
+- **Architecture docs**: Filled Level 2 building blocks (Mermaid diagram, 5 subsystems with code locations) and Level 3 module breakdowns (chat: 9 modules, playout: 6 modules, frontend: 10 modules).
+
+## [1.0.7] - 2026-08-06
+
+### Added
+
+- **Emergency slate fallback**: `scripts/generate-slate.sh` creates "We'll Be Right Back" slate video + pre-rendered HLS. Playout detects FFmpeg failures (>5 restarts/60s) and auto-switches to slate manifest. Health endpoint reports `degraded` mode. Auto-recovers when FFmpeg restarts successfully.
+- **Prometheus metrics**: `linearvoid_playout_restarts_total`, `linearvoid_playout_mode` (0=live, 1=slate), `linearvoid_chat_dms_total` exposed on playout + chat `/metrics`.
+- **Video normalization pipeline**: `scripts/normalize.sh` with env-configurable CRF/preset/audio-bitrate wrapping reference FFmpeg command.
+- **Strict ffprobe verification gate**: `ValidateVideo()` in playout parses ffprobe JSON, checks codec (h264/aac), framerate (30/1), resolution (1280x720 or 1920x1080), pix_fmt (yuv420p), sample_rate (48000), keyframe interval (≤2s). `ValidateVideoStrict()` returns `{valid, errors[]}`.
+- **Upload normalization enforcement**: `validateMediaNormalization()` runs on every admin upload (single + chunked). Non-conforming files get `needs_normalization` status. Visible in media library + playlist validation warnings.
+- **Chat history on room join**: `pushChatHistory()` sends last 50 messages via WebSocket on connect.
+- **DM offline delivery**: Private messages persisted to DB, appear in history when recipient reconnects.
+- **Online presence indicators**: Green dot per user in chat sidebar, updated via join/leave system messages.
+- **Schedule metadata overlay**: "Now Playing" + "Up Next" below viewer player, polling `GET /api/schedule` every 30s. Public `/api/schedule` endpoint added.
+- **Playlist drag-to-reorder**: Sortable list with drag-and-drop, per-entry remove buttons, validation warnings (missing files, needs_normalization).
+- **Schedule overrides**: `ScheduleOverride` model + `GET/POST/DELETE /api/admin/schedule/overrides` with conflict detection (409 on overlap). Admin UI with form + list.
+- **User management actions**: `POST /api/admin/users` with mute/unmute/ban/unban actions. Per-user action buttons in admin users table.
+- **Inline moderation**: Mute/Ban buttons on each chat log entry row in admin.
+- **CSV export**: `GET /api/admin/chat-log/export` returns CSV download.
+- **Analytics time range selector**: 1h, 6h, 24h, 7d dropdown on admin analytics page.
+- **Runtime config editor**: `GET/PUT /api/admin/config` for rate limit max + window. Admin system page with config form + restart buttons.
+- **Production target documentation**: `DEPLOYMENT.md` updated with two-environment model (test lab 192.168.88.0/24 vs Hetzner production TBD), CX22 specs, firewall requirements, DNS cutover plan.
+- **Network diagram**: Mermaid diagram in `SETUP.md` distinguishing test lab from planned production.
+- **E2E test script**: `scripts/test-playout-e2e.sh` for runtime validation in test lab.
+- **Redis pub/sub stub**: Architecture ready for multi-instance chat (pending implementation).
+
+### Changed
+
+- `docker-compose.yml` + `.prod.yml`: added slate volume mount (`./data/slate:/app/slate:ro`), Redis `--maxmemory 256mb --maxmemory-policy allkeys-lru`.
+- `backend/playout/Dockerfile`: added `/app/slate` directory.
+- `handleConnection`: added 30s presence heartbeat + WebSocket ping, banned/muted user checks, env-configurable rate limits (`CHAT_RATE_LIMIT_MAX`, `CHAT_RATE_LIMIT_WINDOW_S`).
+- `handleModerationCommand`: added moderator role check, mute duration parsing, Redis key enforcement.
+- `handlePrivateDM`: targeted delivery via `clientMeta` map instead of broadcast.
+- `initRedis`: added `redisReconnectLoop` with exponential backoff (2s→60s).
+- `handleAdminMedia` + chunked upload: normalization validation runs on every upload, sets `needs_normalization` status.
+- nginx: OPTIONS preflight → 204 on all 4 HLS locations. `/health` returns JSON. `/nginx-status` with stub_status (internal-network restricted).
+- CD workflow: health checks now IP-agnostic (`docker exec` instead of hardcoded IP curls).
+- `docker-compose.yml` + `.prod.yml`, `.gitea/workflows/cd.yml`, `DEPLOYMENT.md`, `SETUP.md`, `docs/architecture/README.md`, `README.md`: all annotated with test-lab vs production distinction, `192.168.88.0/24` flagged as internal test network.
+- `docs/architecture/README.md`: CI/CD deployment view updated to note test lab target, production pending.
+
+### Fixed
+
+- CD health check no longer hardcodes `192.168.88.40` in curl targets — uses `docker exec` for portability.
+- Playlist page no longer single-textarea — now shows sortable list with validation warnings.
+- Schedule page shows overrides alongside playlist timeline.
+
+## [1.0.6] - 2026-08-05
+
+### Added
+
+- `GET /api/admin/chat-log` endpoint with `?room=`, `?limit=`, `?before=`, `?username=`, `?text=` filter/pagination support.
+- `GET /api/admin/chat-log/:id` endpoint returning a single chat log entry as JSON.
+- `DELETE /api/admin/chat-log/:id` endpoint returning 204 No Content on success.
+- `DELETE /api/admin/chat-log/bulk` endpoint accepting `{"ids": [...]}` for bulk deletion (max 500).
+- Chat Log admin tab with table, individual delete with confirmation dialog, pagination (prev/next), search/filter by room/username/text, select-all checkbox, and bulk delete button.
+- Added `"lint": "tsc --noEmit"` script to `frontend/package.json`.
+- `/api/admin/media/{id}` GET/PUT/DELETE handlers for media metadata retrieval, updates, and file+record deletion.
+- Resumable chunked admin media upload flow with upload-session endpoints and client progress indicators.
+- Prometheus-format `/metrics` endpoint for chat runtime and admin-session monitoring.
+- Dedicated operational documentation: `API.md`, `DEPLOYMENT.md`, `MONITORING.md`, `SECURITY.md`.
+
+### Changed
+
+- Split `frontend/admin/index.html` into a template shell plus 9 per-tab page HTML files loaded dynamically via `loadPageContent` / `switchTab` / `bindPageEvents`.
+- Rebuilt viewer, admin, and admin-login pages around custom semantic class structures with accessibility-focused landmarks, tab semantics, and keyboard-focus behavior.
+- Replaced legacy and Tailwind-based stylesheet rules with a custom design-token CSS system covering responsive layouts, forms, tables, and reduced-motion behavior.
+- Switched frontend theme to dark-mode-first token defaults with light-scheme override.
+- Applied new color palette (`#32292f` dark, `#b4c4ae` light, `#587792` brand, `#2ebfa5` focus, `#04650d` ok) across all 22 CSS custom properties in dark and light themes.
+- Replaced hardcoded admin sidebar and tab-trigger colors with CSS custom properties.
+- Optimized CI pipeline: removed duplicate `docker compose build --no-cache` from test job, removed broken playlist validation step, fixed Go module cache path, added Docker Buildx registry cache to docker/release jobs.
+- Bumped chat healthcheck `start_period` from 10s to 30s in `docker-compose.prod.yml`.
+- CD workflow now verifies nginx (port 8080) + chat (3000) + playout (8081); dumps container logs for all failing services.
+- Updated Prometheus scrape targets and Grafana dashboard queries to use live chat metrics.
+
+### Fixed
+
+- Go module cache in CI now correctly references only `backend/chat/go.sum` (playout go.sum did not exist); added `go mod download` step to seed cache.
+- Removed broken playlist validation step (`go run src/playlist.go` without go.mod) from CI test job.
+- Converted nginx CI build from custom shell `docker buildx` to `docker/build-push-action@v5` for cache consistency.
+- Enforced 2GB upload ceiling plus server-side media file type/size validation for admin uploads.
+- Increased nginx `client_max_body_size` to allow resumable admin upload chunks without 413 errors.
+- Removed unused `data-admin-*` Vite env var attributes from admin HTML template.
+- Removed Tailwind and Alpine runtime/build dependencies; eliminated Tailwind directives/warnings during production build.
+
+## [1.0.3] - 2026-08-03
+
+### Added
+
+- Added Prometheus-format `/metrics` endpoint for chat runtime and admin-session monitoring.
+
+### Changed
+
+- Updated Prometheus scrape targets and Grafana dashboard queries to use live chat metrics.
+
+### Fixed
+
+- Fixed nginx routing so `/metrics` is reachable through localhost and `linearvoid.tv`.
+
+## [1.0.2] - 2026-08-03
+
+### Changed
+
+- Updated local environment documentation and examples to prefer real-domain local routing through `linearvoid.tv` and compose-safe internal service hostnames.
+
+### Fixed
+
+- Fixed admin production build output and nginx routing so `/admin/` serves its own entrypoint.
+- Fixed static asset serving so hashed JS/CSS files return correct MIME types and stale asset URLs return `404` instead of SPA HTML.
+- Fixed chat database configuration so `DATABASE_URL` is honored for compose-safe Postgres or SQLite local development.
+
+## [1.0.1] - 2026-08-03
+
+### Changed
+
+- Expanded the setup guide with current `.env.example` variables, development prerequisites, Cloudflare R2 setup, Gitea registry setup, and a production deployment guide.
+- Aligned frontend, nginx, and deployment docs with the `linearvoid.tv` app domain and `media.linearvoid.tv` HLS domain model.
+
 ## [1.0.0] - 2026-08-02
 
-**Full Backend and Frontend Implementation Complete**
+### Added
+
+Full backend and frontend implementation complete.
 
 - **Playout Service** (`backend/playout/`): Go-based playlist management, ffprobe normalization validation, continuous HLS with immutable segment naming, automatic R2 sync, health check endpoint, and Docker integration (ADR-001, ADR-003).
 - **Chat Backend** (`backend/chat/`): Go + Gorilla WebSocket, Redis for presence/rate limiting/pub/sub, SQLite persistence for message history and ModerationLog (ADR-006/ADR-007), public rooms, private DM routing, moderation commands with immutable audit logging, health check endpoint, and docker-compose integration.
 - **Frontend** (`frontend/`): Vite + TypeScript + Tailwind + Alpine.js, HLS player with hls.js, chat sidebar with room switching and private messaging, "Now Playing" overlay, and modern UI (ADR-002, ADR-003).
 - Complete `docker-compose.yml` for local development with all services, volumes, and healthchecks.
 - All ADRs (001-007) created and linked in documentation.
-- `TODO.md`, `DONE.md`, and `CHANGELOG.md` updated with full traceability.
+- `CHANGELOG.md` updated with full traceability.
 - Git repository initialized with comprehensive initial commit.
 
 The project is a fully functional, self-hosted 24/7 linear video channel with synchronized playback, custom chat, R2 delivery, moderation, and admin-ready structure. It matches the architecture defined in the arc42 template and all ADRs.

CONTRIBUTING.md

@@ -7,9 +7,8 @@ Thank you for considering contributing to Linear Void!
 1. **Read the Architecture First**: All design decisions are documented in `docs/architecture/README.md` (arc42 template) and the ADRs in `docs/architecture/adr/` (ADR-001 to ADR-007).
 2. **Follow the Structure**: Use the folder layout defined in ADR-002 (`frontend/`, `backend/playout/`, `backend/chat/`, `infrastructure/`, etc.).
 3. **Update Documentation Before Code**: Create or update an ADR before implementing significant changes.
-4. **Update TODO.md**: Plan tasks in `.github/instructions/TODO.md`, mark as completed, and move finished sections to `DONE.md`.
+4. **Commit Messages**: Reference the relevant ADR (e.g., "feat(playout): add R2 sync per ADR-001").
-5. **Commit Messages**: Reference the relevant ADR (e.g., "feat(playout): add R2 sync per ADR-001").
+5. **Test with Docker**: Run `docker compose up --build` to test changes.
-6. **Test with Docker**: Run `docker compose up --build` to test changes.
 
 ## Repository
 
@@ -20,8 +19,8 @@ Thank you for considering contributing to Linear Void!
 ## Code Style
 
 - Go: Use standard formatting (`go fmt`).
-- TypeScript: ESLint and Prettier.
+- TypeScript: `tsc --noEmit` for type-checking (see `frontend/package.json`).
-- Tailwind: Follow the utility-first approach.
+- CSS: Design-token system via CSS custom properties in `frontend/src/style.css`. No utility framework.
 
 ## Pull Requests
 
@@ -30,4 +29,120 @@ Thank you for considering contributing to Linear Void!
 - Ensure all tests pass and documentation is updated.
 - The CI workflow will validate normalization, linting, and Docker builds.
 
+## Versioning and Releases
+
+### Version Scheme
+
+Linear Void follows **Semantic Versioning** ([SemVer](https://semver.org)): `MAJOR.MINOR.PATCH`.
+
+- **MAJOR** — breaking changes to the viewer, API, or deployment model.
+- **MINOR** — new features (endpoints, admin tabs, UI capabilities) that are backward-compatible.
+- **PATCH** — bug fixes, optimizations, documentation polish.
+
+Git tags use no prefix: `1.0.2`, `1.1.0`, `2.0.0`.
+
+### Where Versions Are Declared
+
+| File                    | Token         | Example                   |
+| ----------------------- | ------------- | ------------------------- |
+| `frontend/package.json` | `"version"`   | `"1.0.2"`                 |
+| `CHANGELOG.md`          | `## [X.Y.Z]`  | `## [1.0.2] - 2026-08-05` |
+| `README.md`             | Version badge | `version-1.0.2-blue`      |
+
+### Tag Triggers
+
+| Tag Pattern            | Workflow            | What Happens                                                                                                       |
+| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `*.*.*` (e.g. `1.0.2`) | `release.yml`       | Builds all 3 images, pushes to registry with semver tags (`1.0.2`, `1.0`, `latest`), creates Gitea Release via API |
+| Push to `main`         | `ci.yml` → `cd.yml` | CI builds + pushes images with `main`/`latest` tags, CD deploys to production                                      |
+
+### Full Release Procedure
+
+#### Step 1: Bump version numbers
+
+Update these files to the new version (replace `X.Y.Z`):
+
+- [frontend/package.json](frontend/package.json)
+- [CHANGELOG.md](CHANGELOG.md) — add new section at top
+- [README.md](README.md) — version badge
+
+```bash
+# frontend/package.json
+"version": "X.Y.Z"
+
+# CHANGELOG.md — add new section at top
+## [X.Y.Z] - YYYY-MM-DD
+
+# README.md — version badge
+version-X.Y.Z-blue
+```
+
+#### Step 2: Write changelog
+
+Add entries under `## [X.Y.Z]` in `CHANGELOG.md` following [Keep a Changelog](https://keepachangelog.com) format (`Added`, `Changed`, `Fixed`, `Removed`).
+
+#### Step 3: Commit and tag
+
+```bash
+# Stage all version bumps + changelog
+git add frontend/package.json CHANGELOG.md README.md
+
+# Commit
+git commit -m "chore: bump version to X.Y.Z"
+
+# Create annotated tag
+git tag -a X.Y.Z -m "Release X.Y.Z"
+
+# Push commit and tag
+git push origin main
+git push origin X.Y.Z
+```
+
+#### Step 4: Verify CI/CD
+
+- CI workflow (`ci.yml`) runs on push to `main` → builds & pushes `main`/`latest` images.
+- Release workflow (`release.yml`) triggers on `X.Y.Z` tag → builds images with semver tags (`X.Y.Z`, `X.Y`, `latest`), creates Gitea Release.
+- CD workflow (`cd.yml`) triggers after CI completes → deploys to production.
+
+Monitor at: [git.allucanget.biz/zwitschi/linearvoid/actions](https://git.allucanget.biz/zwitschi/linearvoid/actions)
+
+#### Step 5: Verify release
+
+Check the Gitea Releases page for the new tag:
+[git.allucanget.biz/zwitschi/linearvoid/releases](https://git.allucanget.biz/zwitschi/linearvoid/releases)
+
+### Manual Release (workflow_dispatch)
+
+If a tag push fails or a re-release is needed:
+
+1. Go to [Actions → Release workflow](https://git.allucanget.biz/zwitschi/linearvoid/actions?workflow=release.yml)
+2. Click "Run workflow"
+3. Enter version (e.g. `1.0.2`)
+4. The workflow builds images, pushes semver tags, and creates the Gitea Release
+
+### Docker Image Tags
+
+Every release produces these tags in the Gitea Container Registry:
+
+| Image     | Tags                     |
+| --------- | ------------------------ |
+| `playout` | `X.Y.Z`, `X.Y`, `latest` |
+| `chat`    | `X.Y.Z`, `X.Y`, `latest` |
+| `nginx`   | `X.Y.Z`, `X.Y`, `latest` |
+
+Example for `1.0.2`:
+
+```text
+git.allucanget.biz/zwitschi/linearvoid/chat:1.0.2
+git.allucanget.biz/zwitschi/linearvoid/chat:1.0
+git.allucanget.biz/zwitschi/linearvoid/chat:latest
+git.allucanget.biz/zwitschi/linearvoid/playout:1.0.2
+git.allucanget.biz/zwitschi/linearvoid/playout:1.0
+git.allucanget.biz/zwitschi/linearvoid/playout:latest
+```
+
+### Moving Completed Tasks
+
+After release, update `CHANGELOG.md` if needed.
+
 See the ADRs for architectural decisions and `docs/architecture/README.md` for the big picture. Thank you for contributing!

DEPLOYMENT.md

@@ -0,0 +1,284 @@
+# Deployment Guide
+
+## Table of Contents
+
+- [Deployment Guide](#deployment-guide)
+  - [Table of Contents](#table-of-contents)
+  - [Environments](#environments)
+  - [Production Target (Hetzner)](#production-target-hetzner)
+    - [Planned Infrastructure](#planned-infrastructure)
+    - [Cutover Plan](#cutover-plan)
+    - [Firewall / Security Group](#firewall--security-group)
+    - [Pipeline Readiness](#pipeline-readiness)
+  - [Target Topology](#target-topology)
+  - [Prerequisites](#prerequisites)
+  - [Environment File](#environment-file)
+  - [Pull-and-Run Deployment](#pull-and-run-deployment)
+  - [First-Time or Recovery Provisioning](#first-time-or-recovery-provisioning)
+  - [Health Verification](#health-verification)
+  - [Zero/Low-Downtime Update Pattern](#zerolow-downtime-update-pattern)
+  - [Rollback](#rollback)
+  - [Operational Tasks](#operational-tasks)
+    - [View logs](#view-logs)
+    - [Restart one service](#restart-one-service)
+    - [Stop stack](#stop-stack)
+    - [Keep volumes (recommended) vs remove volumes (destructive)](#keep-volumes-recommended-vs-remove-volumes-destructive)
+  - [Nginx and Proxy Considerations](#nginx-and-proxy-considerations)
+  - [Security Baseline](#security-baseline)
+  - [Common Deployment Pitfalls](#common-deployment-pitfalls)
+  - [Troubleshooting](#troubleshooting)
+
+## Environments
+
+Linear Void runs in two separate environments:
+
+| Environment    | Host                       | Docker Target              | Purpose                                        |
+| -------------- | -------------------------- | -------------------------- | ---------------------------------------------- |
+| **Test Lab**   | `192.168.88.40` (internal) | `tcp://192.168.88.40:2375` | Integration testing, staging, CI/CD validation |
+| **Production** | Hetzner VPS (TBD)          | `tcp://<hetzner-ip>:2375`  | Public linearvoid.tv serving real viewers      |
+
+**Current state (2026-08-06):** Test lab is active and receives automated CD deploys. Production Hetzner VPS is **not yet provisioned**. The CD workflow (`cd.yml`) and `docker-compose.prod.yml` currently target the test lab. Switching to production requires only changing `DOCKER_HOST` — see [Production Deployment](#production-target-hetzner) below.
+
+## Production Target (Hetzner)
+
+**Status: Not provisioned.** The production deployment plan is documented and the pipeline is ready — only the VPS needs to be created.
+
+### Planned Infrastructure
+
+| Resource       | Spec                                             |
+| -------------- | ------------------------------------------------ |
+| Provider       | Hetzner Cloud                                    |
+| Region         | Ashburn, VA (us-east)                            |
+| Instance       | CX22 (2 vCPU, 4 GB RAM, 40 GB SSD) or equivalent |
+| OS             | Ubuntu 24.04 LTS or Debian 12                    |
+| Bandwidth      | 20 TB included traffic/month                     |
+| Estimated cost | ~€7–10/month base                                |
+
+### Cutover Plan
+
+1. Provision Hetzner VPS (see [Production Deployment](#production-target-hetzner) section)
+2. Add production secrets to Gitea (`CI_PROD_*` prefix)
+3. Update `DOCKER_HOST` in CD workflow to Hetzner public IP
+4. Trigger deploy → validate health checks
+5. Update Cloudflare A record `linearvoid.tv` → Hetzner IP
+6. Enable HTTPS, WAF, cache rules on production zone
+7. Decommission test lab as public target
+
+### Firewall / Security Group
+
+| Port | Source                | Purpose                        |
+| ---- | --------------------- | ------------------------------ |
+| 22   | Admin IPs             | SSH management                 |
+| 80   | 0.0.0.0/0             | HTTP (redirect to HTTPS)       |
+| 443  | 0.0.0.0/0             | HTTPS (nginx)                  |
+| 2375 | Gitea runner IP only  | Docker remote API (TLS)        |
+| 9090 | Admin IPs or internal | Prometheus (or tunnel via SSH) |
+| 3001 | Admin IPs or internal | Grafana (or tunnel via SSH)    |
+
+### Pipeline Readiness
+
+Three Gitea Actions workflows drive the full pipeline:
+
+| Workflow      | Trigger          | Purpose                                                                                  |
+| ------------- | ---------------- | ---------------------------------------------------------------------------------------- |
+| `ci.yml`      | Push to `main`   | Lint, build frontend, vet Go, build & push Docker images (`:latest`, `:main`)            |
+| `cd.yml`      | Push to `main`   | Deploy to test lab (`192.168.88.40:2375`) — runs **in parallel** with CI                 |
+| `release.yml` | Tag push `*.*.*` | Build & push versioned Docker images (`:X.Y.Z`, `:X.Y`, `:latest`), create Gitea Release |
+
+CI and CD run simultaneously on every push to `main`. The deploy pulls whatever `:latest` images are available in the registry at that moment.
+
+The CD workflow (`cd.yml`) uses `DOCKER_HOST` to target the deployment host. To switch targets:
+
+```bash
+# Test lab (current)
+DOCKER_HOST=tcp://192.168.88.40:2375
+
+# Production (when provisioned)
+DOCKER_HOST=tcp://<hetzner-public-ip>:2375
+```
+
+No code changes needed in the pipeline. See `DEPLOYMENT.md` Production Deployment section for full checklist.
+
+## Target Topology
+
+- Host: Linux server with Docker Engine
+- Reverse proxy: nginx container (linearvoid-nginx)
+- Core services: playout, chat, redis, postgres
+- Observability: prometheus, grafana
+- CDN/edge: Cloudflare
+
+## Prerequisites
+
+- Docker Engine + Docker Compose plugin
+- Network access to git.allucanget.biz
+- A valid .env file with production values
+- DNS configured for linearvoid.tv (and media.linearvoid.tv if split media domain is used)
+
+## Environment File
+
+Use .env with at least:
+
+- CI_REGISTRY_URL
+- CI_REGISTRY_NAMESPACE
+- CHAT_PORT
+- NGINX_PORT
+- DATABASE_URL (if overridden)
+- REDIS_URL (if overridden)
+- ADMIN_USERNAME
+- ADMIN_PASSWORD
+- VITE_PUBLIC_APP_URL
+- VITE_PUBLIC_WS_URL
+- VITE_PUBLIC_HLS_URL
+- Cloudflare/R2 variables when media sync is enabled
+
+See .env.example and SETUP.md for full variable reference.
+
+## Pull-and-Run Deployment
+
+Images are built and pushed automatically by the CI and release workflows (see [CONTRIBUTING.md](CONTRIBUTING.md#versioning-and-releases) for the release procedure).
+
+Every push to `main` triggers CI (builds `:main` and `:latest` tags) and CD (deploys `:latest` to test lab) in parallel. Semantic version tags (`*.*.*`, e.g. `1.0.9`) trigger the release workflow which builds `:X.Y.Z`, `:X.Y`, and `:latest` tags and creates a Gitea Release.
+
+From repository root:
+
+```bash
+docker login git.allucanget.biz
+
+docker compose -f docker-compose.prod.yml pull
+docker compose -f docker-compose.prod.yml up -d --remove-orphans
+```
+
+## First-Time or Recovery Provisioning
+
+1. Ensure host paths exist:
+
+```bash
+mkdir -p data/chat data/playlist data/media data/hls
+```
+
+1. Confirm volumes and networks:
+
+```bash
+docker volume ls
+docker network ls
+```
+
+1. Start stack:
+
+```bash
+docker compose -f docker-compose.prod.yml up -d
+```
+
+## Health Verification
+
+After startup, check service status:
+
+```bash
+docker compose -f docker-compose.prod.yml ps
+```
+
+Endpoint checks:
+
+- App: <http://{host}:8080/>
+- Nginx health: <http://{host}:8080/health>
+- Chat health: <http://{host}:3000/health>
+- Playout health: <http://{host}:8081/health>
+- Prometheus: <http://{host}:9090>
+- Grafana: <http://{host}:3001>
+
+Domain checks:
+
+- <https://linearvoid.tv>
+- <https://linearvoid.tv/admin>
+- <https://linearvoid.tv/metrics>
+
+## Zero/Low-Downtime Update Pattern
+
+1. Pull newest images.
+1. Recreate changed services only:
+
+```bash
+docker compose -f docker-compose.prod.yml pull
+
+docker compose -f docker-compose.prod.yml up -d nginx chat playout
+```
+
+1. Re-run health checks.
+
+## Rollback
+
+If new images are unhealthy:
+
+1. Pin previous tags in docker-compose.prod.yml.
+2. Pull pinned tags.
+3. Restart impacted services.
+
+```bash
+docker compose -f docker-compose.prod.yml pull
+
+docker compose -f docker-compose.prod.yml up -d nginx chat playout
+```
+
+## Operational Tasks
+
+### View logs
+
+```bash
+docker compose -f docker-compose.prod.yml logs -f nginx chat playout
+```
+
+### Restart one service
+
+```bash
+docker compose -f docker-compose.prod.yml restart chat
+```
+
+### Stop stack
+
+```bash
+docker compose -f docker-compose.prod.yml down
+```
+
+### Keep volumes (recommended) vs remove volumes (destructive)
+
+```bash
+# keep data
+docker compose -f docker-compose.prod.yml down
+
+# destructive (remove data)
+docker compose -f docker-compose.prod.yml down -v
+```
+
+## Nginx and Proxy Considerations
+
+- If an external proxy (for example Nginx Proxy Manager) fronts the stack, align request body limits with internal nginx.
+- For resumable admin uploads, ensure client_max_body_size supports chunk requests in both proxy layers.
+
+## Security Baseline
+
+- Use strong ADMIN_PASSWORD and rotate regularly.
+- Keep Docker host access restricted.
+- Prefer HTTPS/WSS through Cloudflare.
+- Restrict exposed ports if only proxy access is needed.
+
+## Common Deployment Pitfalls
+
+- Missing frontend build artifacts in local-only compose workflows.
+- Wrong registry credentials or missing login.
+- Misaligned domain env vars (app/ws/hls) causing mixed-origin errors.
+
+## Troubleshooting
+
+| Symptom                    | Check                                         | Fix                                                           |
+| -------------------------- | --------------------------------------------- | ------------------------------------------------------------- |
+| Service not starting       | `docker logs linearvoid-<svc> --tail 50`      | Check `.env` vars, volume mounts, port conflicts              |
+| Playout stall / slate mode | `curl http://<host>:8081/health` — mode=slate | Check playlist file, media paths, disk space                  |
+| Chat not connecting        | `curl http://<host>:3000/health`              | Check Redis: `docker exec linearvoid-redis redis-cli ping`    |
+| Admin 401 loop             | Cookie not sent                               | Verify `X-Forwarded-Proto: https`, nginx auth_request headers |
+| Upload fails (413)         | File too large                                | Check nginx `client_max_body_size` (should be 64m+)           |
+| HLS not playing            | `curl http://<host>/hls/playlist.m3u8`        | Check playout health, HLS dir permissions                     |
+| Prometheus no targets      | `curl http://<host>:9090/targets`             | Verify container network, scrape config                       |
+| Grafana no data            | Check datasource                              | Verify Prometheus URL `http://prometheus:9090` provisioned    |
+
+- Proxy-layer body size limits returning 413 on upload.
+- Health checks failing before service warmup is complete.

MONITORING.md

@@ -0,0 +1,91 @@
+# Monitoring Guide
+
+Prometheus + Grafana monitoring for Linear Void.
+
+## Architecture
+
+```text
+┌──────────────┐     ┌──────────────┐    ┌───────────┐
+│  Exporters   │───> │  Prometheus  │───>│  Grafana  │
+│  (7 targets) │     │  :9090       │    │  :3001    │
+└──────────────┘     └───────┬──────┘    └───────────┘
+                             │
+                   alerts.yml (8 rules)
+```
+
+## Scrape Targets
+
+| Job        | Target            | Port | Metrics                                                       |
+| ---------- | ----------------- | ---- | ------------------------------------------------------------- |
+| chat       | chat              | 3000 | WebSocket clients, messages, DMs, moderation, Redis, sessions |
+| playout    | playout           | 8081 | Restarts, mode (live/slate)                                   |
+| nginx      | nginx-exporter    | 9113 | Requests, connections                                         |
+| redis      | redis-exporter    | 9121 | Memory, clients, commands                                     |
+| postgres   | postgres-exporter | 9187 | Connections, queries, locks                                   |
+| node       | node-exporter     | 9100 | CPU, memory, disk, network                                    |
+| prometheus | prometheus        | 9090 | Self-monitoring                                               |
+
+Config: `monitoring/prometheus/prometheus.yml` (15s scrape interval)
+
+## Alerting Rules
+
+8 rules in `monitoring/prometheus/alerts.yml`:
+
+| Alert                | Severity | Expression                             |
+| -------------------- | -------- | -------------------------------------- |
+| ChatDown             | critical | `up{job="chat"} == 0` for 2m           |
+| PlayoutDown          | critical | `up{job="playout"} == 0` for 2m        |
+| RedisDown            | warning  | `linearvoid_chat_redis_up == 0` for 2m |
+| PlayoutSlateActive   | warning  | `linearvoid_playout_mode == 1` for 1m  |
+| HighChatLatency      | warning  | message rate <0.01/s for 5m            |
+| PrometheusWALFailing | warning  | WAL write failures >0 for 5m           |
+| HighCPU              | warning  | CPU >80% for 10m                       |
+| LowDiskSpace         | warning  | Disk <10% free for 5m                  |
+
+## Access
+
+- Prometheus: `http://<host>:9090` (targets, graph, alerts)
+- Grafana: `http://<host>:3001` (default: admin/admin, change via `GRAFANA_PASSWORD`)
+
+## Dashboards
+
+- **Linear Void app**: `monitoring/grafana/dashboard.json` — clients, messages, moderation, Redis, sessions, scrape health
+- **Prometheus ops**: `monitoring/grafana/dashboards/dashboard.json` — TSDB, CPU/memory, WAL, compactions, query latency
+
+## Key Metrics
+
+- `linearvoid_chat_connected_clients` — active WebSocket connections
+- `linearvoid_chat_messages_total` — total stored messages
+- `linearvoid_chat_dms_total` — private messages sent
+- `linearvoid_chat_redis_up` — Redis reachable (0/1)
+- `linearvoid_playout_restarts_total` — FFmpeg restart counter
+- `linearvoid_playout_mode` — 0=live, 1=slate, 2=degraded
+- `linearvoid_chat_admin_sessions_active` — active admin logins
+
+## Troubleshooting
+
+| Symptom                 | Check                                                                |
+| ----------------------- | -------------------------------------------------------------------- |
+| No chat metrics         | `curl http://chat:3000/metrics` from Prometheus container            |
+| No exporter metrics     | Verify exporter containers running: `docker ps \| grep exporter`     |
+| Grafana no data         | Datasource URL must be `http://prometheus:9090`                      |
+| Prometheus targets down | Check container network: all must be on `linearvoid-net`             |
+| Alert not firing        | Check Prometheus → Alerts tab, verify `rule_files` in prometheus.yml |
+
+### Grafana shows no data
+
+- Ensure datasource points to <http://prometheus:9090>.
+- Confirm Prometheus is healthy.
+- Check dashboard query labels match active jobs.
+
+### High cardinality or query slowness
+
+- Reduce unneeded labels.
+- Limit expensive dashboard panels.
+- Tune retention and query windows.
+
+## Operational Recommendations
+
+- Keep alert thresholds tied to actual user impact.
+- Review dashboards after each release that changes endpoints or metrics names.
+- Periodically test alert routing and incident response flow.

README.md

@@ -1,18 +1,20 @@
 # Linear Void
 
-A self-managed **24/7 linear video channel** for a primarily US audience. It runs a continuous playlist of self-owned videos with true/near-true synchronization, a custom lightweight viewer SPA (hls.js player + chat), and full independence from third-party platforms (YouTube, Twitch, etc.).
+[Linear Void](https://linearvoid.tv) is a self-managed **24/7 linear video channel** for a primarily US audience. It runs a continuous playlist of self-owned videos with true/near-true synchronization, a custom lightweight viewer SPA (hls.js player + chat), and full independence from third-party platforms (YouTube, Twitch, etc.).
 
 **Repository**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid)
 
 [![Build Status](https://git.allucanget.biz/zwitschi/linearvoid/actions/workflows/ci.yml/badge.svg)](https://git.allucanget.biz/zwitschi/linearvoid/actions)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Gitea](https://img.shields.io/badge/Gitea-1.27.1-blue)](https://git.allucanget.biz)
+[![Version](https://img.shields.io/badge/version-1.0.9-blue)](https://git.allucanget.biz/zwitschi/linearvoid/releases)
+[![Release Notes](https://img.shields.io/badge/release-notes-green)](CHANGELOG.md)
 
 ## Architecture
 
 The architecture (detailed in [`docs/architecture/README.md`](docs/architecture/README.md)) uses:
 
-- Hetzner Ashburn VPS for playout (FFmpeg + MediaMTX/SRS) and chat.
+- Hetzner Ashburn VPS for playout (FFmpeg + MediaMTX/SRS) and chat _(planned production; currently test lab at 192.168.88.40)_.
 - Cloudflare R2 + CDN with aggressive immutable caching of HLS `.ts` segments ($0 egress).
 - Lightweight static frontend and WebSocket chat backend.
 - Gitea self-hosted CI/CD (Actions) and Container Registry.
@@ -27,6 +29,23 @@ See [`docs/architecture/adr/`](docs/architecture/adr/) for the full set of decis
 - Video normalization, monitoring, fallback slate, and easy playlist management.
 - US-centric performance (Ashburn origin + Cloudflare POPs).
 
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    V[US Viewers] -->|HTTPS| CF[Cloudflare CDN]
+    CF -->|Cache HIT| R2[Cloudflare R2]
+    CF -->|Cache MISS| N[Nginx :80]
+    N -->|/ws| CH[Chat :3000]
+    N -->|/admin| CH
+    N -->|/hls| P[Playout :8081]
+    N -->|/*| FE[Frontend SPA]
+    CH --> R[(Redis)]
+    CH --> DB[(PostgreSQL)]
+    P -->|ffmpeg| HLS[/data/hls/]
+    P -->|sync| R2
+```
+
 ## Project Structure
 
 ```text
@@ -93,13 +112,22 @@ This structure directly reflects the building blocks, runtime flows, deployment
 
 ## Getting Started
 
+> **Note:** The `docker compose up` below targets local development. The test lab (192.168.88.40) receives automated CD deploys. Production Hetzner VPS is not yet provisioned — see `DEPLOYMENT.md`.
+
 ```bash
 git clone https://git.allucanget.biz/zwitschi/linearvoid.git
 cd linearvoid
 cp .env.example .env
+# Edit .env with your R2 credentials and domain settings
 docker compose up --build
 ```
 
+Then open:
+
+- **Viewer**: [https://linearvoid.tv](https://linearvoid.tv) (or `http://localhost`)
+- **Admin**: [https://linearvoid.tv/admin](https://linearvoid.tv/admin) (or `http://localhost/admin`)
+- **Metrics**: [https://linearvoid.tv/metrics](https://linearvoid.tv/metrics)
+
 Full setup guide: [`SETUP.md`](SETUP.md).
 
 See the [architecture docs](docs/architecture/README.md) for detailed architecture and ADRs.
@@ -107,9 +135,55 @@ See the [architecture docs](docs/architecture/README.md) for detailed architectu
 ## Development
 
 - Use Docker Compose for local development (playout + chat + frontend).
+- Test lab host: `192.168.88.40` (internal network, receives CD deploys). Production Hetzner VPS TBD.
+- Public production host model: `https://linearvoid.tv` for viewer/admin/chat and `https://media.linearvoid.tv` for HLS delivery.
 - Normalize all source videos before adding to playlist (see ADR-001 for exact codec/fps/keyframe requirements).
 - Monitor cache hit ratio and R2 operations closely — they determine real cost.
 
+### Environment Variables
+
+| Variable               | Default                                         | Description                      |
+| ---------------------- | ----------------------------------------------- | -------------------------------- |
+| `R2_ACCESS_KEY_ID`     | —                                               | Cloudflare R2 access key         |
+| `R2_SECRET_ACCESS_KEY` | —                                               | Cloudflare R2 secret key         |
+| `R2_BUCKET_NAME`       | `linearvoid-media`                              | R2 bucket for HLS segments       |
+| `DATABASE_URL`         | `postgres://...@db:5432/...`                    | Chat DB (Postgres or SQLite)     |
+| `REDIS_URL`            | `redis://redis:6379/0`                          | Redis for presence/rate limiting |
+| `VITE_PUBLIC_APP_URL`  | `https://linearvoid.tv`                         | Public viewer URL                |
+| `VITE_PUBLIC_WS_URL`   | `wss://linearvoid.tv/ws`                        | WebSocket endpoint               |
+| `VITE_PUBLIC_HLS_URL`  | `https://media.linearvoid.tv/hls/playlist.m3u8` | HLS playlist URL                 |
+| `ADMIN_USERNAME`       | `admin`                                         | Admin panel username             |
+| `ADMIN_PASSWORD`       | —                                               | Admin panel password             |
+| `HLS_SEGMENT_DURATION` | `6`                                             | HLS segment duration in seconds  |
+| `HLS_WINDOW_SIZE`      | `24`                                            | HLS playlist window size         |
+
+Full reference: [`.env.example`](.env.example).
+
+### Troubleshooting
+
+| Problem                  | Check                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| **Playout not starting** | Verify playlist exists in `data/playlist/playlist.txt` and media files are accessible |
+| **HLS not playing**      | Check `docker compose logs playout` for ffmpeg errors; verify `data/hls/` permissions |
+| **Chat not connecting**  | Ensure Redis is running: `docker compose logs redis`; check `DATABASE_URL`            |
+| **Admin panel 401**      | Verify `ADMIN_USERNAME`/`ADMIN_PASSWORD` in `.env` match login credentials            |
+| **Docker build fails**   | Run `docker compose build --no-cache`; check `backend/playout/.dockerignore`          |
+| **R2 upload failures**   | Verify `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY`; check bucket CORS settings      |
+
+### API Endpoints
+
+| Service     | Endpoint                 | Description                |
+| ----------- | ------------------------ | -------------------------- |
+| **Chat**    | `GET /health`            | Health check               |
+| **Chat**    | `GET /metrics`           | Prometheus metrics         |
+| **Chat**    | `GET /ws`                | WebSocket upgrade for chat |
+| **Chat**    | `GET /api/admin/*`       | Admin API (auth required)  |
+| **Chat**    | `POST /api/admin/login`  | Admin login                |
+| **Playout** | `GET /health`            | Health check (port 8081)   |
+| **Nginx**   | `GET /`                  | Viewer SPA                 |
+| **Nginx**   | `GET /admin/`            | Admin panel                |
+| **Nginx**   | `GET /hls/playlist.m3u8` | HLS manifest               |
+
 ## Architecture Documentation
 
 The architecture is fully documented using the [arc42 template](docs/architecture/README.md) (with populated sections, Mermaid context and building-block diagrams, deployment view, cross-cutting concepts, quality goals, risks, and glossary).
@@ -133,6 +207,10 @@ Contributions, issues, and further evolution (LL-HLS, ABR, multi-channel, E2EE)
 - [CHANGELOG.md](CHANGELOG.md) - Version history and completed features.
 - [CONTRIBUTING.md](CONTRIBUTING.md) - Guidelines for contributing to the project.
 - [SETUP.md](SETUP.md) - Complete setup guide with prerequisites, environment configuration, running the application, and troubleshooting.
+- [API.md](API.md) - Implemented WebSocket and REST API reference.
+- [DEPLOYMENT.md](DEPLOYMENT.md) - Production deployment and operations guide.
+- [MONITORING.md](MONITORING.md) - Prometheus and Grafana setup and troubleshooting.
+- [SECURITY.md](SECURITY.md) - Security controls, hardening checklist, and incident baseline.
 - [Architecture Documentation](docs/architecture/README.md) - Full arc42 template with diagrams and decisions.
 - [ADRs](docs/architecture/adr/) - Detailed decision records (ADR-001 to ADR-007).
 
@@ -140,4 +218,17 @@ Contributions, issues, and further evolution (LL-HLS, ABR, multi-channel, E2EE)
 
 **Container Registry**: `git.allucanget.biz/zwitschi/linearvoid/<service>:latest`
 
+## Contributing
+
+Contributions are welcome! See [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines. Quick overview:
+
+1. Read the [architecture docs](docs/architecture/README.md) and ADRs first.
+2. Code against the defined module structure (frontend, backend/playout, backend/chat, infrastructure, scripts, monitoring).
+3. Open PRs on [Gitea](https://git.allucanget.biz/zwitschi/linearvoid).
+4. CI validates builds and tests automatically.
+
+Since this a linear project, we also rely on a linear development and release model: Only main branch is used for releases, and all features are merged into main after review and CI validation. Releases are tagged with semantic versioning (1.0.3, 1.0.4, etc.) and automatically built/pushed to the container registry. Version numbers are declared in `frontend/package.json`, `CHANGELOG.md`, and the version badge in this README. For patches, we use even numbers for stable versions (1.0.2, 1.0.4) and odd numbers for pre-release/unstable versions (1.0.3, 1.0.5).
+
+[MIT License](LICENSE)
+
 The project is ready for use. See [`SETUP.md`](SETUP.md) for detailed installation instructions.

SECURITY.md

@@ -0,0 +1,93 @@
+# Security Guide
+
+Layered security model for Linear Void.
+
+## Threat Model
+
+```
+┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
+│  Client  │───▶│Cloudflare│───▶│  nginx   │───▶│  Backend │
+│ (public) │    │ WAF+CDN  │    │ proxy    │    │ chat     │
+└──────────┘    └──────────┘    └────┬─────┘    └────┬─────┘
+                                     │                │
+                              ┌──────┴──────┐  ┌─────┴──────┐
+                              │ /health     │  │ /api/admin │
+                              │ /metrics    │  │ /ws (chat)  │
+                              │ /hls/*      │  │ /api/chat/* │
+                              │ (public)    │  │ (auth req)  │
+                              └─────────────┘  └────────────┘
+```
+
+## Authentication & Sessions
+
+- Login: `POST /api/admin/login` → cookie `linearvoid_admin_session`
+- Cookie flags: `HttpOnly`, `SameSite=Strict`, `Secure` (over HTTPS)
+- Server-side expiry via `ADMIN_SESSION_TTL_HOURS`
+- Rate limit: 5 attempts/IP/5min via Redis
+
+## Transport Security (TLS/HSTS)
+
+- Cloudflare TLS mode: **Full (strict)** — valid origin cert required
+- nginx listens on 80 internally; Cloudflare handles TLS termination
+- HSTS header set by Cloudflare: `max-age=31536000; includeSubDomains; preload`
+- WSS upgrade path: `/ws` through nginx → chat:3000
+
+## Network Isolation
+
+- All backend services on internal Docker network (`linearvoid-net`)
+- Only nginx port exposed to host (443/80)
+- Database, Redis, exporters inaccessible from outside
+- `docker-compose.prod.yml` keeps ports internal via `expose:` not `ports:`
+
+## Reverse Proxy Controls
+
+- `auth_request /api/admin/auth` gate on all `/admin` and `/api/admin` paths
+- Explicit `client_max_body_size 64m` for resumable upload chunks
+- WebSocket upgrade headers: `Upgrade`, `Connection` preserved
+- CORS headers on HLS: `Access-Control-Allow-Origin *`
+- XSS protection: CSP headers served by Cloudflare
+
+## Rate Limiting
+
+| Resource          | Limit | Window |
+| ----------------- | ----- | ------ |
+| WebSocket connect | 5/IP  | 60s    |
+| Chat messages     | 10/IP | 10s    |
+| Admin login       | 5/IP  | 5min   |
+
+Implemented via Redis `INCR` + `EXPIRE`.
+
+## Secrets Management
+
+- `.env` — local dev only, **gitignored**
+- Gitea Actions secrets (`CI_*` prefix) for CI/CD
+- Never commit: passwords, tokens, API keys, R2 credentials
+- Production `.env` provisioned manually on host, never checked in
+- Rotate admin password quarterly
+
+## Data Protection
+
+- PostgreSQL: chat history, moderation logs, media metadata
+- Redis: append-only persistence for presence, rate limits, sessions
+- HLS segments: ephemeral, regenerated by playout
+- Backups: `scripts/backup-db.sh` (daily), `scripts/backup-weekly.sh`, `scripts/verify-backups.sh`
+
+## Hardening Checklist
+
+- [ ] HTTPS/WSS enforced end-to-end (Cloudflare Full strict)
+- [ ] Strong admin credentials configured
+- [ ] Secrets only in env/secrets stores (never committed)
+- [ ] Proxy auth and websocket headers validated
+- [ ] Upload limits and MIME validation active
+- [ ] Rate limiting active (WS, messages, login)
+- [ ] Cloudflare WAF/rate-limit rules active
+- [ ] Backup/restore drills completed
+- [ ] Security alerts routed (Prometheus alertmanager)
+
+## Incident Response
+
+1. Detect — alerts (ChatDown, RedisDown, HighChatLatency) or user reports
+2. Triage — edge (Cloudflare), proxy (nginx), app (chat/playout), data (Redis/Postgres)
+3. Contain — rate limit, credential rotate, service restart, slate mode activation
+4. Recover — verify health endpoints, check Prometheus targets, validate HLS output
+5. Record — timeline + corrective actions in `docs/incident-runbook.md`

SETUP.md

@@ -5,12 +5,67 @@ This guide covers prerequisites, environment setup, running the application loca
 ## Prerequisites
 
 - **Docker & Docker Compose**: Required for running the full stack (playout, chat, nginx, redis, db, prometheus, grafana). Install from [docker.com](https://www.docker.com).
-- **Node.js 20+**: For frontend development (`cd frontend && npm run dev`).
+- **Node.js 20+**: Required for frontend development and production builds (`cd frontend && npm install && npm run build`).
+- **npm**: Installed with Node.js and used for the frontend dependency installation and Vite workflow.
+- **Go 1.23+**: Recommended when working on the Go services outside Docker (`backend/chat`, `backend/playout`).
 - **FFmpeg**: Used by the playout service for HLS generation. Install via `apt install ffmpeg` (Linux), Homebrew (macOS), or Winget (Windows).
 - **Git**: For cloning and version control.
 - **Cloudflare Account**: For R2 storage and CDN (free tier sufficient for most use cases).
+- **Gitea Account**: Required if you want to push images to the self-hosted registry or use the repository's CI/CD flow.
+  - Set up the required Actions secrets in Gitea at: [https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets](https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets)
+  - Add the following secrets:
+    - `CI_REGISTRY_USER`: Your Gitea username (e.g., `zwitschi`)
+    - `CI_REGISTRY_TOKEN`: A Gitea Personal Access Token with `write:packages` scope
+    - `ADMIN_USERNAME`: The administrator username for the production admin panel (e.g., `admin`)
+    - `ADMIN_PASSWORD`: A strong password for the production admin panel
+    - `DATABASE_URL`: The production database connection string (e.g., `postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`)
 - **Hetzner Cloud Account** (optional for production): For the US-East VPS (Ashburn, VA recommended per ADR-001).
 
+## Network Environments
+
+Linear Void operates in two distinct environments. Know which one you're targeting.
+
+```mermaid
+flowchart LR
+    subgraph Test_Lab["Test Lab (192.168.88.0/24)"]
+        TEST_HOST["192.168.88.40<br/>Docker Engine :2375"]
+    end
+
+    subgraph Prod["Production (Hetzner — NOT provisioned)"]
+        PROD_HOST["Hetzner CX22 Ashburn, VA<br/>Public IP TBD"]
+    end
+
+    subgraph Gitea["Gitea CI/CD"]
+        CI["CI: build + push images"]
+        CD["CD: deploy via DOCKER_HOST"]
+    end
+
+    subgraph CF["Cloudflare"]
+        DNS["linearvoid.tv"]
+        R2["R2 Bucket"]
+    end
+
+    CD -->|"DOCKER_HOST=tcp://192.168.88.40:2375"| TEST_HOST
+    CD -.->|"DOCKER_HOST=tcp://&lt;hetzner-ip&gt;:2375<br/>(when provisioned)"| PROD_HOST
+    TEST_HOST -->|"test traffic"| DNS
+    PROD_HOST -.->|"production traffic"| DNS
+    TEST_HOST --> R2
+    PROD_HOST -.-> R2
+```
+
+**Test Lab (active):** Internal network `192.168.88.0/24`, host `192.168.88.40`. Receives automated CD deploys from Gitea Actions. Used for integration testing and staging validation.
+
+**Production (pending):** Hetzner Cloud VPS, Ashburn VA. Not yet provisioned. CD workflow and compose files are ready — only `DOCKER_HOST` needs changing. See Production Deployment section in [DEPLOYMENT.md](./DEPLOYMENT.md) for cutover plan.
+
+## Development Prerequisites
+
+- **Frontend dependencies**: Run `cd frontend && npm install` before `npm run dev` or `npm run build`.
+- **Docker build support**: Local development expects Docker to be able to build the `chat`, `playout`, and `nginx` images referenced in `docker-compose.yml`.
+- **Data directories**: Create `data/playlist`, `data/media`, `data/hls`, and `data/chat` before the first run so bind mounts resolve cleanly.
+- **Database choice**: The stack defaults to PostgreSQL in `docker-compose.yml`. If you want SQLite for local-only development, update `DATABASE_URL` in `.env` accordingly.
+- **Redis availability**: Chat presence, rate limiting, and pub/sub require Redis. The compose stack provides it automatically.
+- **Video inputs**: Source videos should be normalized before playout. If the playlist contains invalid files, the playout container will fail its validation flow.
+
 ## Environment Setup
 
 1. **Clone the Repository** (if not already done):
@@ -34,45 +89,148 @@ This guide covers prerequisites, environment setup, running the application loca
    R2_SECRET_ACCESS_KEY=your-r2-secret-key
    R2_BUCKET_NAME=linearvoid-media
    R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
+   R2_REGION=auto
 
    # Cloudflare (for custom domain and cache rules)
    CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
-   MEDIA_DOMAIN=media.example.com
+   CLOUDFLARE_ACCOUNT_ID=your-account-id
+   MEDIA_DOMAIN=media.linearvoid.tv
+
+   # Public frontend URLs
+   # Preferred local setup uses the real public domains through Cloudflare and Nginx Proxy Manager.
+   VITE_PUBLIC_APP_URL=https://linearvoid.tv
+   VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws
+   VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8
+   VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR=admin
+   VITE_PUBLIC_ADMIN_DEFAULT_ROOM=main
+   VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT=50
+   ADMIN_USERNAME=admin
+   ADMIN_PASSWORD=change-me
+   ADMIN_SESSION_TTL_HOURS=12
+   # Optional direct-local fallback when bypassing the public proxy:
+   # VITE_PUBLIC_APP_URL=http://localhost
+   # VITE_PUBLIC_WS_URL=ws://localhost/ws
+   # VITE_PUBLIC_HLS_URL=http://localhost/hls/playlist.m3u8
 
    # Gitea Container Registry (for self-hosted Docker images)
-   GITEA_REGISTRY_URL=git.allucanget.biz
+   CI_REGISTRY_URL=git.allucanget.biz
-   GITEA_USERNAME=your-gitea-username
+   CI_REGISTRY_USER=your-gitea-username
-   GITEA_TOKEN=your-gitea-token
+   CI_REGISTRY_TOKEN=your-gitea-token
-   GITEA_REGISTRY_NAMESPACE=zwitschi/linearvoid
+   CI_REGISTRY_NAMESPACE=zwitschi/linearvoid
+   # Gitea API access (optional, for CI/release automation)
+   CI_SERVER_URL=https://git.allucanget.biz
 
    # Chat / Database
+   DATABASE_URL=postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable
+   # or for SQLite-only local development:
+   # DATABASE_URL=sqlite://./data/chat.db
    REDIS_URL=redis://redis:6379/0
-   DATABASE_URL=sqlite://./data/chat.db   # or postgres://user:pass@db:5432/linearvoid
 
    # Ports (for local development)
+   PLAYOUT_PORT=8080
    CHAT_PORT=3000
-   NGINX_PORT=8080
+   NGINX_PORT=80
-   PLAYOUT_HEALTH_PORT=8081
 
    # Playout Configuration
-   PLAYLIST_PATH=/app/playlist/playlist.txt
+   PLAYLIST_PATH=/app/playlist.txt
    HLS_SEGMENT_DURATION=6
    HLS_WINDOW_SIZE=24
 
-   # Logging
+   # Logging / Monitoring
    LOG_LEVEL=info
+   PROMETHEUS_PORT=9090
+   GRAFANA_PORT=3001
+
+   # Development flags
+   NODE_ENV=development
+   GO_ENV=development
    ```
 
-4. **Create Data Directories**:
+4. **Check local value overrides for Docker Compose**:
+   - `docker-compose.yml` builds images locally and maps the frontend build output from `frontend/dist` into nginx.
+   - `docker-compose.prod.yml` pulls prebuilt images from the Gitea registry.
+   - Internal container-to-container URLs should use compose hostnames, for example `REDIS_URL=redis://redis:6379/0` and `DATABASE_URL=postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`.
+   - For production public routing, set `VITE_PUBLIC_APP_URL=https://linearvoid.tv`, `VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws`, and `VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8`.
+
+5. **Create Data Directories**:
 
    ```bash
    mkdir -p data/playlist data/media data/hls data/chat
    ```
 
-5. **Prepare Sample Videos** (optional):
+6. **Prepare Sample Videos** (optional):
    - Place normalized MP4 files in `data/media/`.
    - Create a `data/playlist/playlist.txt` with paths (see ADR-001 for normalization requirements).
 
+## Cloudflare R2 Setup
+
+1. **Create an R2 bucket**:
+   - Create a bucket such as `linearvoid-media` in Cloudflare R2.
+   - Keep the bucket name aligned with `R2_BUCKET_NAME` in `.env`.
+
+2. **Generate R2 API credentials**:
+   - Create an access key pair with read/write permissions for the bucket.
+   - Set `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, and `R2_REGION=auto` in `.env`.
+
+3. **Find the S3 endpoint**:
+   - Use the account-scoped endpoint format `https://<account-id>.r2.cloudflarestorage.com`.
+   - Store the account ID in both `R2_ENDPOINT` and `CLOUDFLARE_ACCOUNT_ID` where applicable.
+
+4. **Bind a custom media domain**:
+   - Attach a domain such as `media.linearvoid.tv` to the bucket.
+   - Set `MEDIA_DOMAIN` to that hostname.
+
+5. **Configure app-domain DNS and TLS**:
+   - Point `linearvoid.tv` to the public entrypoint serving nginx.
+   - Point `www.linearvoid.tv` to the same target and redirect it to `https://linearvoid.tv`.
+   - Keep `media.linearvoid.tv` on the R2 custom domain path so HLS delivery stays split from the app origin.
+   - Use Cloudflare proxied DNS with Full (strict) TLS so browser traffic uses `https://linearvoid.tv`, `wss://linearvoid.tv/ws`, and `https://media.linearvoid.tv`.
+
+6. **Apply cache behavior**:
+   - Configure the `.ts` and `.m3u8` cache rules from `infrastructure/cloudflare/cache-rules.md`.
+   - Enable Smart Tiered Cache for the R2-backed hostname.
+   - If you need header normalization for immutable segment caching, deploy `infrastructure/cloudflare/worker.js` to the same zone.
+
+7. **Verify access**:
+   - Confirm uploads with an S3-compatible client such as `aws s3 ls --endpoint-url <R2_ENDPOINT>`.
+   - After deployment, check Cloudflare analytics for cache hit ratio and origin request volume.
+
+## Gitea Setup
+
+1. **Create or verify a Gitea user**:
+   - The user should have access to the repository and permission to read from the container registry.
+
+2. **Create an access token**:
+   - Generate a token with the scopes needed for package/registry access and, if applicable, repository automation.
+   - Store it as `CI_REGISTRY_TOKEN` in `.env`.
+
+3. **Configure Gitea Actions Secrets**:
+   - Go to the repository settings page: [https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets](https://git.allucanget.biz/zwitschi/linearvoid/settings/actions/secrets)
+   - Add the following secrets to enable automated CI/CD and production deployment:
+     - `CI_REGISTRY_USER`: Your Gitea username (e.g., `zwitschi`).
+     - `CI_REGISTRY_TOKEN`: Your Gitea Personal Access Token with `write:packages` scope.
+     - `ADMIN_USERNAME`: The administrator username for the production admin panel (e.g., `admin`).
+     - `ADMIN_PASSWORD`: A strong password for the production admin panel.
+     - `DATABASE_URL`: The production database connection string (e.g., `postgres://linearvoid:<password>@db:5432/linearvoid?sslmode=disable`).
+
+4. **Configure registry variables**:
+   - Set `CI_REGISTRY_URL` to the Gitea host.
+   - Set `CI_REGISTRY_NAMESPACE` to the image namespace, for example `zwitschi/linearvoid`.
+   - Set `CI_REGISTRY_USER` to the account that will push or pull images.
+
+5. **Authenticate Docker to the registry**:
+
+   ```bash
+   docker login git.allucanget.biz
+   ```
+
+6. **Build and publish images when needed**:
+   - Local development uses `docker-compose.yml`, which builds from source.
+   - Production uses `docker-compose.prod.yml`, which expects the `playout`, `chat`, and `nginx` images to exist in the configured Gitea registry namespace.
+
+7. **Validate image availability**:
+   - Before a production rollout, verify that the expected `:latest` tags can be pulled from the registry on the target server.
+
 ## Running the Application
 
 ### Local Development
@@ -84,9 +242,10 @@ This guide covers prerequisites, environment setup, running the application loca
    ```
 
 2. **Access the Application**:
-   - Viewer: <http://localhost:8080>
+   - Preferred local access with the documented proxy setup: <https://linearvoid.tv>
-   - Chat WebSocket: ws://localhost:3000/ws
+   - Admin Interface: <https://linearvoid.tv/admin> (redirects to `/admin/login/` until authenticated)
-   - Admin Interface: <http://localhost:8080/admin> (use the credentials from `.env` or default admin/admin)
+   - Chat WebSocket: `wss://linearvoid.tv/ws`
+   - Direct-local fallback when bypassing Cloudflare/Nginx Proxy Manager: <http://localhost>, <http://localhost/admin>, and `ws://localhost/ws`
    - Health Checks:
      - Playout: <http://localhost:8081/health>
      - Chat: <http://localhost:3000/health>
@@ -98,23 +257,184 @@ This guide covers prerequisites, environment setup, running the application loca
 
    ```bash
    cd frontend
+   npm install
    npm run dev
    ```
 
    The dev server runs on <http://localhost:5173>. It proxies API calls to the backend services.
 
-4. **Stop Services**:
+4. **Build frontend assets for nginx-backed local runs**:
+
+   ```bash
+   cd frontend
+   npm install
+   npm run build
+   ```
+
+   The local nginx container serves `frontend/dist`, so rebuilding the frontend is required before validating production-like static output.
+
+5. **Stop Services**:
 
    ```bash
    docker compose down
    ```
 
+### Local Test Environment Deployment (Remote Docker Host)
+
+For testing deployments on a local network server without setting up a full production VPS, you can deploy directly to a remote Docker host (e.g., a home lab server or test machine) using Docker's TCP socket.
+
+#### Test Environment Prerequisites
+
+- A remote server running Docker at IP `192.168.88.40` (running Alpine Linux).
+- Docker TCP socket enabled and listening on port `2375` on the remote server.
+
+##### Enabling Docker TCP Socket on Alpine Linux
+
+To allow the Gitea Actions runner (or your local machine) to deploy to the remote Alpine host, you must configure the Docker daemon to listen on the TCP socket:
+
+1. Edit `/etc/conf.d/docker` on the Alpine host:
+
+   ```bash
+   vi /etc/conf.d/docker
+   ```
+
+2. Update the `DOCKER_OPTS` line to include both the unix socket and the TCP socket:
+
+   ```bash
+   DOCKER_OPTS="-H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375"
+   ```
+
+3. Restart the Docker service:
+
+   ```bash
+   rc-service docker restart
+   ```
+
+4. Verify that Docker is listening on port `2375`:
+
+   ```bash
+   netstat -tlnp | grep 2375
+   ```
+
+5. Ensure any firewall (like `awall` or `iptables`) on the Alpine host allows incoming traffic on port `2375` from your local network subnet (e.g., `192.168.88.0/24`).
+
+#### Deployment Steps
+
+1. **Configure Docker CLI to use the Remote Host**:
+   You can point your local Docker CLI to the remote server by setting the `DOCKER_HOST` environment variable:
+   - **PowerShell (Windows)**:
+
+     ```powershell
+     $env:DOCKER_HOST="tcp://192.168.88.40:2375"
+     ```
+
+   - **Bash (Linux/macOS)**:
+
+     ```bash
+     export DOCKER_HOST="tcp://192.168.88.40:2375"
+     ```
+
+2. **Verify Connection**:
+   Run `docker info` to confirm your local CLI is communicating with the remote server at `192.168.88.40`:
+
+   ```bash
+   docker info
+   ```
+
+   The output should show the remote server's hostname and system details.
+
+3. **Deploy the Stack**:
+   With `DOCKER_HOST` set, any `docker` or `docker compose` commands you run locally will execute directly on the remote server.
+   - **Deploy from Registry (Production-like)**:
+
+     ```bash
+     docker compose -f docker-compose.prod.yml pull
+     docker compose -f docker-compose.prod.yml up -d --remove-orphans
+     ```
+
+   - **Build and Deploy from Source**:
+
+     ```bash
+     docker compose up -d --build
+     ```
+
+4. **Access the Test Environment**:
+   - Playout Health: `http://192.168.88.40:8081/health`
+   - Chat Health: `http://192.168.88.40:3000/health`
+   - Nginx Entrypoint: `http://192.168.88.40:8080` (or the port mapped to `NGINX_PORT` in `.env`)
+
+5. **Reset to Local Docker Host**:
+   Once testing is complete, clear the `DOCKER_HOST` variable to point back to your local machine:
+   - **PowerShell**:
+
+     ```powershell
+     Remove-Item env:DOCKER_HOST
+     ```
+
+   - **Bash**:
+
+     ```bash
+     unset DOCKER_HOST
+     ```
+
+### Production Setup Guide
+
+1. **Prepare the target host**:
+   - Provision a Linux VPS with Docker Engine, Docker Compose, Git, and enough disk for media, HLS output, PostgreSQL, Redis persistence, and monitoring data.
+   - Open the ports required for HTTP/HTTPS and any restricted monitoring access you intend to expose.
+
+2. **Clone the repository and create the environment file**:
+
+   ```bash
+   git clone https://git.allucanget.biz/zwitschi/linearvoid.git
+   cd linearvoid
+   cp .env.example .env
+   ```
+
+3. **Set production-safe `.env` values**:
+   - Replace placeholder secrets.
+   - Use compose-network hostnames for internal services, for example `redis` and `db`.
+   - Set strong values for `POSTGRES_PASSWORD` and `GRAFANA_PASSWORD`.
+   - Keep `MEDIA_DOMAIN`, R2 credentials, and Gitea registry values consistent with the external infrastructure.
+   - Set `MEDIA_DOMAIN=media.linearvoid.tv`.
+   - Set `VITE_PUBLIC_APP_URL=https://linearvoid.tv`, `VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws`, and `VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8`.
+   - If you intentionally bypass the public proxy for local-only testing, switch those values to `http://localhost`, `ws://localhost/ws`, and `http://localhost/hls/playlist.m3u8`.
+
+4. **Create runtime directories on the server**:
+
+   ```bash
+   mkdir -p data/playlist data/media data/hls data/chat
+   ```
+
+5. **Publish or verify required images in Gitea**:
+   - Ensure the `playout`, `chat`, and `nginx` images exist under `${CI_REGISTRY_URL}/${CI_REGISTRY_NAMESPACE}`.
+   - Log in to the registry from the VPS before pulling.
+
+6. **Deploy the production stack**:
+
+   ```bash
+   docker compose -f docker-compose.prod.yml pull
+   docker compose -f docker-compose.prod.yml up -d
+   ```
+
+7. **Run post-deploy verification**:
+   - Check `docker compose -f docker-compose.prod.yml ps`.
+   - Confirm nginx, chat, and playout health endpoints respond.
+   - Verify that HLS output is being written to `data/hls` and that the media domain serves manifests and segments through Cloudflare.
+
+8. **Harden and operate the deployment**:
+   - Put HTTPS in front of nginx using Cloudflare or another reverse proxy, with `linearvoid.tv` as canonical app host and `www.linearvoid.tv` redirected.
+   - Restrict Grafana and Prometheus exposure to trusted IPs or a private network.
+   - Run the stack under systemd or another service manager if you need auto-start behavior outside Docker restart policies.
+
 ### Production Deployment (Hetzner VPS + Cloudflare)
 
 1. **Provision VPS**: Use Hetzner Cloud CX22 in Ashburn, VA (per ADR-001).
 2. **Configure Cloudflare**:
    - Create R2 bucket with `enam` location hint.
-   - Set up custom domain (`media.example.com`) with the cache rules from `infrastructure/cloudflare/cache-rules.md`.
+   - Set up custom media domain (`media.linearvoid.tv`) with the cache rules from `infrastructure/cloudflare/cache-rules.md`.
+   - Point `linearvoid.tv` and `www.linearvoid.tv` at the app entrypoint, then redirect `www` to the apex domain.
+   - Use Full (strict) TLS for both app and media hostnames.
    - Apply the Worker from `infrastructure/cloudflare/worker.js` for advanced header management.
 3. **Deploy**:
    - Copy the project to the VPS.
@@ -132,7 +452,8 @@ See `docs/architecture/README.md` for the full arc42 documentation and the ADRs
 - **Chat Not Connecting**: Check Redis connection and WebSocket URL. The health check at `/health` should return 200.
 - **Cache Not Working**: Verify Cloudflare cache rules (`.ts` = long TTL immutable, `.m3u8` = short TTL). Check cache hit ratio in Cloudflare dashboard.
 - **Docker Issues**: Run `docker compose logs` for service-specific errors. Ensure ports are not in use.
-- **Admin Interface**: Ensure the protected route is configured in nginx and authentication is set up (default is open for local development).
+- **Admin Interface**: Ensure `ADMIN_USERNAME`, `ADMIN_PASSWORD`, and `ADMIN_SESSION_TTL_HOURS` are set. `/admin/` and `/api/admin/*` are protected by a session-based login flow.
+- **Production Pull Fails**: Confirm `docker login` to Gitea succeeded on the server and the image tags referenced by `docker-compose.prod.yml` exist.
 
 ## Further Reading
 
@@ -143,4 +464,4 @@ See `docs/architecture/README.md` for the full arc42 documentation and the ADRs
 
 The system is ready for use. For production, review ADR-001 for cost estimates and scaling guidance.
 
-**Last Updated**: 2026-08-02
+**Last Updated**: 2026-08-03

backend/chat/Dockerfile

@@ -1,17 +1,17 @@
-FROM golang:1.23-alpine AS builder
+FROM golang:1.25-alpine AS builder
+
+RUN apk add --no-cache gcc musl-dev
 
 WORKDIR /app
+COPY go.mod ./
 COPY src/ ./src/
-COPY go.mod go.sum ./
+RUN go mod tidy
-
+RUN CGO_ENABLED=1 GOOS=linux go build -o /chat-server ./src/main.go
-RUN go mod download
-RUN CGO_ENABLED=0 GOOS=linux go build -o /chat-server ./src/main.go
 
 FROM alpine:3.20
-RUN apk --no-cache add ca-certificates
+RUN apk --no-cache add ca-certificates curl ffmpeg
 WORKDIR /app
-COPY --from=builder /chat-server .
+COPY --from=builder /chat-server /usr/local/bin/chat-server
-COPY config/ ./config/
 
 EXPOSE 3000
-CMD ["./chat-server"]
+CMD ["/usr/local/bin/chat-server"]

backend/chat/go.mod

@@ -1,10 +1,11 @@
 module chat
 
-go 1.23
+go 1.25.0
 
 require (
 	github.com/gorilla/websocket v1.5.3
 	github.com/redis/go-redis/v9 v9.7.0
+	gorm.io/driver/postgres v1.5.11
 	gorm.io/driver/sqlite v1.5.7
 	gorm.io/gorm v1.25.12
 )
@@ -12,7 +13,14 @@ require (
 require (
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/pgx/v5 v5.7.5 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/mattn/go-sqlite3 v1.14.22 // indirect
+	golang.org/x/crypto v0.37.0 // indirect
+	golang.org/x/sync v0.13.0 // indirect
+	golang.org/x/text v0.24.0 // indirect
 )

backend/chat/go.sum

@@ -0,0 +1,52 @@
+github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
+github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
+github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
+github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.7.5 h1:JHGfMnQY+IEtGM63d+NGMjoRpysB2JBwDr5fsngwmJs=
+github.com/jackc/pgx/v5 v5.7.5/go.mod h1:aruU7o91Tc2q2cFp5h4uP3f6ztExVpyVv88Xl/8Vl8M=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
+github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/redis/go-redis/v9 v9.7.0 h1:HhLSs+B6O021gwzl+locl0zEDnyNkxMtf/Z3NNBMa9E=
+github.com/redis/go-redis/v9 v9.7.0/go.mod h1:f6zhXITC7JUJIlPEiBOTXxJgPLdZcA93GewI7inzyWw=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
+github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
+golang.org/x/crypto v0.37.0 h1:kJNSjF/Xp7kU0iB2Z+9viTPMW4EqqsrywMXLJOOsXSE=
+golang.org/x/crypto v0.37.0/go.mod h1:vg+k43peMZ0pUMhYmVAWysMK35e6ioLh3wB8ZCAfbVc=
+golang.org/x/sync v0.13.0 h1:AauUjRAJ9OSnvULf/ARrrVywoJDy0YS2AwQ98I37610=
+golang.org/x/sync v0.13.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
+golang.org/x/text v0.24.0 h1:dd5Bzh4yt5KYA8f9CJHCP4FB4D51c2c6JvN37xJJkJ0=
+golang.org/x/text v0.24.0/go.mod h1:L8rBsPeo2pSS+xqN0d5u2ikmjtmoJbDBT1b7nHvFCdU=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/postgres v1.5.11 h1:ubBVAfbKEUld/twyKZ0IYn9rSQh448EdelLYk9Mv314=
+gorm.io/driver/postgres v1.5.11/go.mod h1:DX3GReXH+3FPWGrrgffdvCk3DQ1dwDPdmbenSkweRGI=
+gorm.io/driver/sqlite v1.5.7 h1:8NvsrhP0ifM7LX9G4zPB97NwovUakUxc+2V2uuf3Z1I=
+gorm.io/driver/sqlite v1.5.7/go.mod h1:U+J8craQU6Fzkcvu8oLeAQmi50TkwPEhHDEjQZXDah4=
+gorm.io/gorm v1.25.12 h1:I0u8i2hWQItBq1WfE0o2+WuL9+8L21K9e2HHSTE/0f8=
+gorm.io/gorm v1.25.12/go.mod h1:xh7N7RHfYlNc5EmcI/El95gXusucDrQnHXe0+CgWcLQ=

backend/playout/Dockerfile

@@ -1,8 +1,7 @@
-FROM golang:1.23-alpine AS builder
+FROM golang:1.25-alpine AS builder
 
 WORKDIR /app
 COPY src/ ./src/
-COPY go.mod go.sum ./
 
 # Initialize Go module if not present
 RUN go mod init playout || true
@@ -17,20 +16,19 @@ RUN apk add --no-cache \
     ffmpeg \
     curl \
     bash
-
+# Set working directory for playout
 WORKDIR /app
-
+# Create directories for playlist, media, HLS output, and emergency slate
-COPY --from=builder /playlist-manager /app/playlist-manager
+RUN mkdir -p /app/hls /app/media /app/playlists /app/slate
+# Copy the playout start script and the built playlist manager binary
 COPY start-playout.sh /app/
-COPY *.sh /app/
+# Copy demo data for out-of-the-box playout
-
+COPY demodata/ /app/
-RUN chmod +x /app/*.sh /app/playlist-manager
+# Copy the built playlist manager binary from the builder stage
-
+COPY --from=builder /playlist-manager /app/playlist-manager
-# Create directories for playlist, media, and HLS output
+# Set execute permissions for the start script and playlist manager binary
-RUN mkdir -p /app/playlist /app/media /app/hls
+RUN chmod +x /app/start-playout.sh /app/playlist-manager
-
 # Expose HLS directory (will be served by nginx)
 VOLUME ["/app/hls"]
-
 # Default command runs the playout loop (which calls the Go validator)
 CMD ["./start-playout.sh"]

backend/playout/demodata/playlist/playlist.txt

@@ -0,0 +1,3 @@
+# Linear Void Demo Playlist
+file '/app/media/demo1.mp4'
+file '/app/media/demo2.mp4'

backend/playout/src/playlist.go

@@ -3,11 +3,13 @@ package main
 import (
 	"bufio"
 	"context"
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
 	"strings"
 	"time"
 
@@ -25,8 +27,18 @@ type VideoFile struct {
 }
 
 var (
-	r2Client *s3.Client
+	r2Client      *s3.Client
-	bucket   = os.Getenv("R2_BUCKET_NAME")
+	bucket        = os.Getenv("R2_BUCKET_NAME")
+	playoutMode   = "starting" // "live", "slate", "degraded"
+	restartCount  = 0
+	restartWindow = time.Now()
+	slateDir      = "/app/slate"
+	hlsDir        = "/app/hls"
+)
+
+const (
+	maxRestartsPerMinute = 5
+	slateManifestName    = "playlist.m3u8"
 )
 
 // initR2Client initializes the R2 (S3-compatible) client
@@ -64,6 +76,12 @@ func LoadPlaylist(playlistPath string) ([]VideoFile, error) {
 		if line == "" || strings.HasPrefix(line, "#") {
 			continue
 		}
+
+		if strings.HasPrefix(line, "file ") {
+			line = strings.TrimSpace(strings.TrimPrefix(line, "file "))
+			line = strings.Trim(line, "'\"")
+		}
+
 		videos = append(videos, VideoFile{Path: line})
 	}
 
@@ -73,23 +91,181 @@ func LoadPlaylist(playlistPath string) ([]VideoFile, error) {
 // ValidateVideo uses ffprobe to enforce codec, fps, and keyframe interval (ADR-001)
 func ValidateVideo(videoPath string) (VideoFile, error) {
 	v := VideoFile{Path: videoPath}
+	var errors []string
 
+	// Run ffprobe
 	cmd := exec.Command("ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", videoPath)
 	output, err := cmd.Output()
 	if err != nil {
 		v.Validation = "ffprobe failed: " + err.Error()
-		return v, err
+		return v, fmt.Errorf("ffprobe: %w", err)
 	}
 
-	// TODO: Parse JSON for strict checks (codec_name=h264, r_frame_rate=30/1, key_frame interval)
+	// Parse JSON
-	// For MVP we assume valid if ffprobe succeeds
+	var probe struct {
-	v.Valid = true
+		Streams []struct {
-	v.Validation = "Validation passed (H.264/AVC, AAC, 30fps constant, 2s keyframes - full JSON parse TODO per ADR-001)"
+			CodecName  string `json:"codec_name"`
-	v.Duration = 60.0 // placeholder from ffprobe
+			CodecType  string `json:"codec_type"`
+			Width      int    `json:"width"`
+			Height     int    `json:"height"`
+			RFrameRate string `json:"r_frame_rate"`
+			PixFmt     string `json:"pix_fmt"`
+			SampleRate string `json:"sample_rate"`
+			Channels   int    `json:"channels"`
+			Duration   string `json:"duration"`
+		} `json:"streams"`
+		Format struct {
+			Duration string `json:"duration"`
+		} `json:"format"`
+	}
+	if err := json.Unmarshal(output, &probe); err != nil {
+		v.Validation = "ffprobe JSON parse failed: " + err.Error()
+		return v, fmt.Errorf("ffprobe json: %w", err)
+	}
 
+	if len(probe.Streams) == 0 {
+		errors = append(errors, "no streams detected")
+	}
+
+	var hasVideo, hasAudio bool
+	for _, s := range probe.Streams {
+		switch s.CodecType {
+		case "video":
+			hasVideo = true
+			if s.CodecName != "h264" {
+				errors = append(errors, fmt.Sprintf("video codec must be h264, got %s", s.CodecName))
+			}
+			if s.RFrameRate != "30/1" {
+				errors = append(errors, fmt.Sprintf("framerate must be 30/1, got %s", s.RFrameRate))
+			}
+			if s.Width != 1280 && s.Width != 1920 {
+				errors = append(errors, fmt.Sprintf("width must be 1280 or 1920, got %d", s.Width))
+			}
+			if s.Height != 720 && s.Height != 1080 {
+				errors = append(errors, fmt.Sprintf("height must be 720 or 1080, got %d", s.Height))
+			}
+			if s.PixFmt != "yuv420p" {
+				errors = append(errors, fmt.Sprintf("pixel format must be yuv420p, got %s", s.PixFmt))
+			}
+		case "audio":
+			hasAudio = true
+			if s.CodecName != "aac" {
+				errors = append(errors, fmt.Sprintf("audio codec must be aac, got %s", s.CodecName))
+			}
+			if s.SampleRate != "48000" {
+				errors = append(errors, fmt.Sprintf("audio sample rate must be 48000, got %s", s.SampleRate))
+			}
+		}
+	}
+
+	if !hasVideo {
+		errors = append(errors, "no video stream found")
+	}
+	if !hasAudio {
+		errors = append(errors, "no audio stream found")
+	}
+
+	// Parse duration from format or stream
+	durationSec := 0.0
+	if probe.Format.Duration != "" {
+		if d, err := strconv.ParseFloat(probe.Format.Duration, 64); err == nil {
+			durationSec = d
+		}
+	}
+
+	if len(errors) > 0 {
+		v.Valid = false
+		v.Validation = strings.Join(errors, "; ")
+		return v, fmt.Errorf("validation failed: %s", v.Validation)
+	}
+
+	// Validate keyframe interval <=2s (60 frames at 30fps)
+	keyframeErr := validateKeyframeInterval(videoPath)
+	if keyframeErr != nil {
+		errors = append(errors, keyframeErr.Error())
+	}
+
+	if len(errors) > 0 {
+		v.Valid = false
+		v.Validation = strings.Join(errors, "; ")
+		return v, fmt.Errorf("validation failed: %s", v.Validation)
+	}
+
+	v.Valid = true
+	v.Duration = durationSec
+	v.Validation = fmt.Sprintf("OK: H.264/AAC, 30fps, yuv420p, 48kHz, %.1fs, keyframes OK", durationSec)
 	return v, nil
 }
 
+// validateKeyframeInterval checks that max gap between keyframes <=2s (60 frames at 30fps).
+func validateKeyframeInterval(videoPath string) error {
+	cmd := exec.Command("ffprobe",
+		"-v", "quiet",
+		"-select_streams", "v:0",
+		"-show_frames",
+		"-show_entries", "frame=key_frame,pkt_pts_time",
+		"-of", "csv=p=0",
+		videoPath)
+	output, err := cmd.Output()
+	if err != nil {
+		return fmt.Errorf("keyframe probe failed: %w", err)
+	}
+
+	type kfEntry struct{ pts float64 }
+	var keyframes []kfEntry
+	lines := strings.Split(strings.TrimSpace(string(output)), "\n")
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		parts := strings.Split(line, ",")
+		if len(parts) < 2 || parts[0] != "1" {
+			continue
+		}
+		pts, err := strconv.ParseFloat(strings.TrimSpace(parts[1]), 64)
+		if err != nil {
+			continue
+		}
+		keyframes = append(keyframes, kfEntry{pts})
+	}
+
+	if len(keyframes) < 2 {
+		return fmt.Errorf("insufficient keyframes for interval analysis (need >=2, got %d)", len(keyframes))
+	}
+
+	maxGap := 0.0
+	for i := 1; i < len(keyframes); i++ {
+		gap := keyframes[i].pts - keyframes[i-1].pts
+		if gap > maxGap {
+			maxGap = gap
+		}
+	}
+
+	if maxGap > 2.1 { // small tolerance for floating point
+		return fmt.Errorf("keyframe interval too large: max %.2fs (must be <=2s)", maxGap)
+	}
+
+	return nil
+}
+
+// ValidateVideoStrict runs ValidateVideo and returns a structured JSON result.
+func ValidateVideoStrict(videoPath string) map[string]any {
+	v, err := ValidateVideo(videoPath)
+	result := map[string]any{
+		"path":   videoPath,
+		"valid":  v.Valid,
+		"errors": []string{},
+	}
+	if err != nil {
+		result["errors"] = strings.Split(v.Validation, "; ")
+	}
+	if v.Valid {
+		result["duration_seconds"] = v.Duration
+	}
+	return result
+}
+
 // ValidatePlaylist runs normalization validation on all entries
 func ValidatePlaylist(playlistPath string) ([]VideoFile, error) {
 	videos, err := LoadPlaylist(playlistPath)
@@ -133,8 +309,105 @@ func SyncToR2(localPath, r2Key string) error {
 // HealthHandler provides a simple health check endpoint
 func HealthHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
+	status := "healthy"
+	if playoutMode == "slate" {
+		status = "degraded"
+	}
 	w.WriteHeader(http.StatusOK)
-	fmt.Fprint(w, `{"status":"healthy","service":"playout","timestamp":"`+time.Now().UTC().Format(time.RFC3339)+`"}`)
+	fmt.Fprintf(w, `{"status":"%s","service":"playout","mode":"%s","restarts":%d,"timestamp":"%s"}`,
+		status, playoutMode, restartCount, time.Now().UTC().Format(time.RFC3339))
+}
+
+// activateSlate copies pre-rendered slate HLS into the live output directory.
+// Writes a static manifest referencing slate segments. Returns error if slate not found.
+func activateSlate() error {
+	slateHLS := filepath.Join(slateDir, "hls")
+	if _, err := os.Stat(filepath.Join(slateHLS, "slate.m3u8")); os.IsNotExist(err) {
+		return fmt.Errorf("slate HLS not found at %s — run scripts/generate-slate.sh first", slateHLS)
+	}
+
+	// Clear existing live segments
+	if err := resetHLSOutput(hlsDir); err != nil {
+		return fmt.Errorf("failed to clear HLS output for slate: %w", err)
+	}
+
+	// Copy slate segments into live HLS dir
+	slateFiles, err := filepath.Glob(filepath.Join(slateHLS, "*"))
+	if err != nil {
+		return err
+	}
+	for _, src := range slateFiles {
+		dst := filepath.Join(hlsDir, filepath.Base(src))
+		data, err := os.ReadFile(src)
+		if err != nil {
+			return err
+		}
+		if err := os.WriteFile(dst, data, 0o644); err != nil {
+			return err
+		}
+	}
+
+	playoutMode = "slate"
+	fmt.Printf("[%s] EMERGENCY: Switched to slate fallback. %d restarts in window.\n",
+		time.Now().Format(time.RFC3339), restartCount)
+	return nil
+}
+
+// deactivateSlate clears slate state and prepares for live playout resumption.
+func deactivateSlate() {
+	playoutMode = "live"
+	fmt.Printf("[%s] RECOVERY: Slate deactivated, resuming live playout.\n",
+		time.Now().Format(time.RFC3339))
+}
+
+// shouldEscalateToSlate checks if restart count exceeds threshold within the window.
+func shouldEscalateToSlate() bool {
+	if time.Since(restartWindow) > 60*time.Second {
+		restartCount = 0
+		restartWindow = time.Now()
+		return false
+	}
+	return restartCount >= maxRestartsPerMinute
+}
+
+func resetHLSOutput(hlsDir string) error {
+	if err := os.MkdirAll(hlsDir, 0o755); err != nil {
+		return err
+	}
+
+	matches, err := filepath.Glob(filepath.Join(hlsDir, "segment_*.ts"))
+	if err != nil {
+		return err
+	}
+
+	for _, match := range matches {
+		if err := os.Remove(match); err != nil && !os.IsNotExist(err) {
+			return err
+		}
+	}
+
+	fmp4Matches, err := filepath.Glob(filepath.Join(hlsDir, "segment_*.m4s"))
+	if err != nil {
+		return err
+	}
+
+	for _, match := range fmp4Matches {
+		if err := os.Remove(match); err != nil && !os.IsNotExist(err) {
+			return err
+		}
+	}
+
+	manifestPath := filepath.Join(hlsDir, "playlist.m3u8")
+	if err := os.Remove(manifestPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+
+	initPath := filepath.Join(hlsDir, "init.mp4")
+	if err := os.Remove(initPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+
+	return nil
 }
 
 func main() {
@@ -161,6 +434,21 @@ func main() {
 
 	// Start HTTP health check server
 	http.HandleFunc("/health", HealthHandler)
+	http.HandleFunc("/metrics", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
+		fmt.Fprintln(w, "# HELP linearvoid_playout_restarts_total Total FFmpeg restarts.")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_restarts_total counter")
+		fmt.Fprintf(w, "linearvoid_playout_restarts_total %d\n", restartCount)
+		fmt.Fprintln(w, "# HELP linearvoid_playout_mode Current playout mode (0=live, 1=slate, 2=degraded).")
+		fmt.Fprintln(w, "# TYPE linearvoid_playout_mode gauge")
+		modeVal := 0
+		if playoutMode == "slate" {
+			modeVal = 1
+		} else if playoutMode == "degraded" {
+			modeVal = 2
+		}
+		fmt.Fprintf(w, "linearvoid_playout_mode %d\n", modeVal)
+	})
 	go func() {
 		fmt.Println("Health check server listening on :8081/health")
 		if err := http.ListenAndServe(":8081", nil); err != nil {
@@ -168,25 +456,64 @@ func main() {
 		}
 	}()
 
-	// Run FFmpeg in a loop for continuous playback with R2 sync hook
+	// Run FFmpeg in a loop for continuous playback with slate fallback
 	for {
-		fmt.Printf("[%s] Starting FFmpeg playout with -c copy (immutable segments for Cloudflare caching)...\n", time.Now().Format(time.RFC3339))
+		if playoutMode == "slate" {
+			// During slate: attempt recovery by restarting FFmpeg
+			fmt.Printf("[%s] Slate active — attempting live playout recovery...\n", time.Now().Format(time.RFC3339))
+		}
+
+		if err := resetHLSOutput(hlsDir); err != nil {
+			fmt.Println("Failed to reset HLS output:", err)
+			time.Sleep(5 * time.Second)
+			continue
+		}
+
+		fmt.Printf("[%s] Starting FFmpeg playout with browser-safe H.264/AAC HLS encoding...\n", time.Now().Format(time.RFC3339))
 
 		cmd := exec.Command("ffmpeg", "-re", "-f", "concat", "-safe", "0", "-i", playlistPath,
-			"-c:v", "copy", "-c:a", "copy",
+			"-map", "0:v:0", "-map", "0:a:0?",
+			"-vf", "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,fps=30,format=yuv420p",
+			"-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p",
+			"-profile:v", "high", "-level", "4.0",
+			"-r", "30", "-g", "60", "-keyint_min", "60", "-sc_threshold", "0",
+			"-c:a", "aac", "-ar", "48000", "-ac", "2", "-b:a", "128k",
 			"-f", "hls",
 			"-hls_time", "6",
 			"-hls_list_size", "24",
-			"-hls_flags", "delete_segments+append_list+independent_segments",
+			"-hls_segment_type", "fmp4",
-			"-hls_segment_filename", "/app/hls/segment_%Y%m%d_%H%M%S_%%03d.ts", // unique immutable names per ADR-001
+			"-hls_fmp4_init_filename", "init.mp4",
+			"-strftime", "1",
+			"-hls_flags", "delete_segments+independent_segments",
+			"-hls_segment_filename", "/app/hls/segment_%Y%m%d_%H%M%S.m4s",
 			"/app/hls/playlist.m3u8")
 
-		if err := cmd.Run(); err != nil {
+		runErr := cmd.Run()
-			fmt.Println("FFmpeg exited with error. Restarting in 5s (per ADR-001 resilience)...")
+
+		// Track restart and check for slate escalation
+		restartCount++
+		fmt.Printf("[%s] FFmpeg exited (restart #%d in window): %v\n",
+			time.Now().Format(time.RFC3339), restartCount, runErr)
+
+		if shouldEscalateToSlate() {
+			fmt.Printf("[%s] CRITICAL: %d restarts in 60s — escalating to slate fallback\n",
+				time.Now().Format(time.RFC3339), restartCount)
+			if err := activateSlate(); err != nil {
+				fmt.Printf("[%s] Slate activation failed: %v — will retry\n",
+					time.Now().Format(time.RFC3339), err)
+			}
+			// Stay in slate mode, retry recovery after delay
+			time.Sleep(30 * time.Second)
+			continue
+		}
+
+		// If we were in slate but FFmpeg ran successfully, we recovered
+		if playoutMode == "slate" {
+			deactivateSlate()
 		}
 
 		// After FFmpeg run, sync latest segments and manifest to R2
-		if err := syncLatestToR2("/app/hls"); err != nil {
+		if err := syncLatestToR2(hlsDir); err != nil {
 			fmt.Println("R2 sync warning:", err)
 		}
 
@@ -196,7 +523,7 @@ func main() {
 
 // syncLatestToR2 uploads new segments and the playlist manifest to R2
 func syncLatestToR2(hlsDir string) error {
-	files, err := filepath.Glob(filepath.Join(hlsDir, "segment_*.ts"))
+	files, err := filepath.Glob(filepath.Join(hlsDir, "segment_*.m4s"))
 	if err != nil {
 		return err
 	}
@@ -215,6 +542,10 @@ func syncLatestToR2(hlsDir string) error {
 	if err := SyncToR2(manifestPath, "live/playlist.m3u8"); err != nil {
 		return err
 	}
+	initPath := filepath.Join(hlsDir, "init.mp4")
+	if err := SyncToR2(initPath, "live/init.mp4"); err != nil {
+		return err
+	}
 	fmt.Println("Synced live playlist.m3u8 to R2")
 
 	return nil

backend/playout/start-playout.sh

@@ -26,16 +26,27 @@ fi
 
 echo "Playlist validated successfully. Starting continuous HLS playout..."
 
+mkdir -p /app/hls
+rm -f /app/hls/playlist.m3u8 /app/hls/init.mp4 /app/hls/segment_*.ts /app/hls/segment_*.m4s
+
 # Run FFmpeg in a loop for continuous playback
 while true; do
-  echo "[$(date)] Starting FFmpeg playout with -c copy (stream copy mode)..."
+  echo "[$(date)] Starting FFmpeg playout with browser-safe HLS encoding..."
   ffmpeg -re -f concat -safe 0 -i "$PLAYLIST_PATH" \
-    -c:v copy -c:a copy \
+    -map 0:v:0 -map 0:a:0? \
+    -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2,fps=30,format=yuv420p" \
+    -c:v libx264 -preset veryfast -pix_fmt yuv420p \
+    -profile:v high -level 4.0 \
+    -r 30 -g 60 -keyint_min 60 -sc_threshold 0 \
+    -c:a aac -ar 48000 -ac 2 -b:a 128k \
     -f hls \
     -hls_time "${HLS_SEGMENT_DURATION}" \
     -hls_list_size "${HLS_WINDOW_SIZE}" \
-    -hls_flags delete_segments+append_list \
+    -hls_segment_type fmp4 \
-    -hls_segment_filename "/app/hls/segment_%03d.ts" \
+    -hls_fmp4_init_filename init.mp4 \
+    -strftime 1 \
+    -hls_flags delete_segments+independent_segments \
+    -hls_segment_filename "/app/hls/segment_%Y%m%d_%H%M%S.m4s" \
     "/app/hls/playlist.m3u8" || echo "FFmpeg exited with error (will restart in 5s per ADR-001 resilience requirements)..."
 
   echo "Playout loop crashed or ended. Restarting in 5 seconds..."

docker-compose.prod.yml

@@ -1,3 +1,9 @@
+# docker-compose.prod.yml — TEST LAB DEPLOYMENT
+# Target: test lab host 192.168.88.40 (NOT Hetzner production).
+# Production Hetzner VPS not yet provisioned — see DEPLOYMENT.md Production Deployment section.
+# Uses pre-built images from Gitea Container Registry (no local build).
+# Override DOCKER_HOST in CD workflow to switch target.
+
 services:
   playout:
     image: git.allucanget.biz/zwitschi/linearvoid/playout:latest
@@ -6,9 +12,10 @@ services:
     env_file:
       - .env
     volumes:
-      - ./data/playlist:/app/playlist:ro
+      - ./data/playlist:/app/playlist:rw
       - ./data/media:/app/media:ro
       - ./data/hls:/app/hls:rw
+      - ./data/slate:/app/slate:ro
     networks:
       - linearvoid-net
     depends_on:
@@ -30,6 +37,8 @@ services:
       - "${CHAT_PORT:-3000}:3000"
     volumes:
       - ./data/chat:/app:rw
+      - ./data/playlist:/app/playlist:rw
+      - ./data/media:/app/media:rw
     networks:
       - linearvoid-net
     depends_on:
@@ -40,7 +49,7 @@ services:
       interval: 10s
       timeout: 5s
       retries: 5
-      start_period: 10s
+      start_period: 30s
 
   nginx:
     image: git.allucanget.biz/zwitschi/linearvoid/nginx:latest
@@ -49,7 +58,7 @@ services:
     ports:
       - "${NGINX_PORT:-8080}:80"
     volumes:
-      - ./data/hls:/usr/share/nginx/html/hls:ro
+      - ./data/hls:/srv/hls:ro
     networks:
       - linearvoid-net
     depends_on:
@@ -66,7 +75,7 @@ services:
     image: redis:7-alpine
     container_name: linearvoid-redis
     restart: unless-stopped
-    command: redis-server --appendonly yes
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
     volumes:
       - redis-data:/data
     networks:
@@ -95,12 +104,62 @@ services:
       timeout: 5s
       retries: 5
 
+  nginx-exporter:
+    image: nginx/nginx-prometheus-exporter:latest
+    container_name: linearvoid-nginx-exporter
+    restart: unless-stopped
+    command:
+      - "-nginx.scrape-uri=http://nginx/nginx-status"
+    networks:
+      - linearvoid-net
+    depends_on:
+      - nginx
+
+  redis-exporter:
+    image: oliver006/redis_exporter:latest
+    container_name: linearvoid-redis-exporter
+    restart: unless-stopped
+    command:
+      - "-redis.addr=redis://redis:6379"
+    networks:
+      - linearvoid-net
+    depends_on:
+      - redis
+
+  postgres-exporter:
+    image: prometheuscommunity/postgres-exporter:latest
+    container_name: linearvoid-postgres-exporter
+    restart: unless-stopped
+    environment:
+      DATA_SOURCE_NAME: "postgresql://linearvoid:${POSTGRES_PASSWORD:-linearvoid}@db:5432/linearvoid?sslmode=disable"
+    networks:
+      - linearvoid-net
+    depends_on:
+      - db
+
+  node-exporter:
+    image: prom/node-exporter:latest
+    container_name: linearvoid-node-exporter
+    restart: unless-stopped
+    pid: host
+    volumes:
+      - /proc:/host/proc:ro
+      - /sys:/host/sys:ro
+      - /:/rootfs:ro
+    command:
+      - "--path.procfs=/host/proc"
+      - "--path.sysfs=/host/sys"
+      - "--path.rootfs=/rootfs"
+      - "--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)"
+    networks:
+      - linearvoid-net
+
   prometheus:
     image: prom/prometheus:latest
     container_name: linearvoid-prometheus
     restart: unless-stopped
     volumes:
-      - ./monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
+      - prometheus-config:/etc/prometheus
       - prometheus-data:/prometheus
     ports:
       - "9090:9090"
@@ -139,5 +198,6 @@ networks:
 volumes:
   redis-data:
   postgres-data:
+  prometheus-config:
   prometheus-data:
   grafana-data:

docker-compose.yml

@@ -1,8 +1,11 @@
-version: "3.9"
+# docker-compose.yml — LOCAL DEVELOPMENT
+# Target: local workstation or test lab (192.168.88.0/24).
+# NOT for production. Use docker-compose.prod.yml for deployment.
+# Services build from source; ports exposed for direct dev access.
 
 services:
   playout:
-    image: ${GITEA_REGISTRY_URL:-git.allucanget.biz}/${GITEA_REGISTRY_NAMESPACE:-zwitschi/linearvoid}/playout:latest
+    image: ${CI_REGISTRY_URL:-git.allucanget.biz}/${CI_REGISTRY_NAMESPACE:-zwitschi/linearvoid}/playout:latest
     build:
       context: ./backend/playout
       dockerfile: Dockerfile
@@ -14,6 +17,7 @@ services:
       - ./data/playlist:/app/playlist:ro
       - ./data/media:/app/media:ro
       - ./data/hls:/app/hls:rw
+      - ./data/slate:/app/slate:ro
     networks:
       - linearvoid-net
     depends_on:
@@ -26,7 +30,7 @@ services:
       start_period: 10s
 
   chat:
-    image: ${GITEA_REGISTRY_URL:-git.allucanget.biz}/${GITEA_REGISTRY_NAMESPACE:-zwitschi/linearvoid}/chat:latest
+    image: ${CI_REGISTRY_URL:-git.allucanget.biz}/${CI_REGISTRY_NAMESPACE:-zwitschi/linearvoid}/chat:latest
     build:
       context: ./backend/chat
       dockerfile: Dockerfile
@@ -38,6 +42,8 @@ services:
       - "${CHAT_PORT:-3000}:3000"
     volumes:
       - ./data/chat:/app:rw
+      - ./data/playlist:/app/playlist:rw
+      - ./data/media:/app/media:rw
     networks:
       - linearvoid-net
     depends_on:
@@ -51,17 +57,17 @@ services:
       start_period: 10s
 
   nginx:
-    image: ${GITEA_REGISTRY_URL:-git.allucanget.biz}/${GITEA_REGISTRY_NAMESPACE:-zwitschi/linearvoid}/nginx:latest
+    image: ${CI_REGISTRY_URL:-git.allucanget.biz}/${CI_REGISTRY_NAMESPACE:-zwitschi/linearvoid}/nginx:latest
     build:
-      context: ./infrastructure/nginx
+      context: .
-      dockerfile: Dockerfile
+      dockerfile: infrastructure/nginx/Dockerfile
     container_name: linearvoid-nginx
     restart: unless-stopped
     ports:
       - "${NGINX_PORT:-8080}:80"
     volumes:
-      - ./frontend/dist:/usr/share/nginx/html:ro
+      - ./frontend/dist:/srv/frontend:ro
-      - ./data/hls:/usr/share/nginx/html/hls:ro
+      - ./data/hls:/srv/hls:ro
     networks:
       - linearvoid-net
     depends_on:
@@ -72,7 +78,7 @@ services:
     image: redis:7-alpine
     container_name: linearvoid-redis
     restart: unless-stopped
-    command: redis-server --appendonly yes
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
     volumes:
       - redis-data:/data
     networks:
@@ -91,12 +97,63 @@ services:
     networks:
       - linearvoid-net
 
+  nginx-exporter:
+    image: nginx/nginx-prometheus-exporter:latest
+    container_name: linearvoid-nginx-exporter
+    restart: unless-stopped
+    command:
+      - "-nginx.scrape-uri=http://nginx/nginx-status"
+    networks:
+      - linearvoid-net
+    depends_on:
+      - nginx
+
+  redis-exporter:
+    image: oliver006/redis_exporter:latest
+    container_name: linearvoid-redis-exporter
+    restart: unless-stopped
+    command:
+      - "-redis.addr=redis://redis:6379"
+    networks:
+      - linearvoid-net
+    depends_on:
+      - redis
+
+  postgres-exporter:
+    image: prometheuscommunity/postgres-exporter:latest
+    container_name: linearvoid-postgres-exporter
+    restart: unless-stopped
+    environment:
+      DATA_SOURCE_NAME: "postgresql://linearvoid:${POSTGRES_PASSWORD:-linearvoid}@db:5432/linearvoid?sslmode=disable"
+    networks:
+      - linearvoid-net
+    depends_on:
+      - db
+
+  node-exporter:
+    image: prom/node-exporter:latest
+    container_name: linearvoid-node-exporter
+    restart: unless-stopped
+    pid: host
+    volumes:
+      - /proc:/host/proc:ro
+      - /sys:/host/sys:ro
+      - /:/rootfs:ro
+    command:
+      - "--path.procfs=/host/proc"
+      - "--path.sysfs=/host/sys"
+      - "--path.rootfs=/rootfs"
+      - "--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)"
+    networks:
+      - linearvoid-net
+
   prometheus:
     image: prom/prometheus:latest
     container_name: linearvoid-prometheus
     restart: unless-stopped
     volumes:
       - ./monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
+      - ./monitoring/prometheus/alerts.yml:/etc/prometheus/alerts.yml
       - prometheus-data:/prometheus
     ports:
       - "9090:9090"

docs/architecture/README.md

@@ -4,18 +4,93 @@
 
 ## Table of Contents
 
-- [Introduction and Goals](#introduction-and-goals)
+- [Architecture Documentation for Linear Void](#architecture-documentation-for-linear-void)
-- [Architecture Constraints](#architecture-constraints)
+  - [Table of Contents](#table-of-contents)
-- [Context and Scope](#context-and-scope)
+  - [Companion Documentation](#companion-documentation)
-- [Solution Strategy](#solution-strategy)
+  - [Introduction and Goals](#introduction-and-goals)
-- [Building Block View](#building-block-view)
+    - [Requirements Overview](#requirements-overview)
-- [Runtime View](#runtime-view)
+    - [Quality Goals](#quality-goals)
-- [Deployment View](#deployment-view)
+    - [Stakeholders](#stakeholders)
-- [Cross-cutting Concepts](#cross-cutting-concepts)
+  - [Architecture Constraints](#architecture-constraints)
-- [Architecture Decisions](#architecture-decisions)
+  - [Context and Scope](#context-and-scope)
-- [Quality Requirements](#quality-requirements)
+    - [Business Context](#business-context)
-- [Risks and Technical Debts](#risks-and-technical-debts)
+    - [High-Level Context Diagram (Mermaid)](#high-level-context-diagram-mermaid)
-- [Glossary](#glossary)
+    - [Technical Context](#technical-context)
+  - [Solution Strategy](#solution-strategy)
+  - [Building Block View](#building-block-view)
+    - [Whitebox Overall System](#whitebox-overall-system)
+    - [Level 2](#level-2)
+      - [Playout Service (`backend/playout/src/playlist.go`)](#playout-service-backendplayoutsrcplaylistgo)
+      - [Chat Service (`backend/chat/src/main.go`)](#chat-service-backendchatsrcmaingo)
+      - [Frontend SPA (`frontend/`)](#frontend-spa-frontend)
+      - [Reverse Proxy (`infrastructure/nginx/nginx.conf`)](#reverse-proxy-infrastructurenginxnginxconf)
+    - [Level 3](#level-3)
+      - [Chat Service Modules](#chat-service-modules)
+      - [Playout Service Modules](#playout-service-modules)
+      - [Frontend Modules](#frontend-modules)
+  - [Runtime View](#runtime-view)
+    - [Playout \& Delivery Scenario](#playout--delivery-scenario)
+  - [Deployment View](#deployment-view)
+    - [CI/CD Pipeline Architecture](#cicd-pipeline-architecture)
+    - [Infrastructure Level 1](#infrastructure-level-1)
+    - [Infrastructure Level 2](#infrastructure-level-2)
+  - [Cross-cutting Concepts](#cross-cutting-concepts)
+    - [Caching \& Cost Optimization](#caching--cost-optimization)
+    - [Video Normalization \& Playout](#video-normalization--playout)
+      - [Required Source Profile (Linear Void v1)](#required-source-profile-linear-void-v1)
+      - [Reference Normalization Command](#reference-normalization-command)
+      - [Verification Gate (ffprobe)](#verification-gate-ffprobe)
+    - [Monitoring \& Resilience](#monitoring--resilience)
+      - [Prometheus Baseline](#prometheus-baseline)
+      - [Grafana Dashboards](#grafana-dashboards)
+      - [Alerting Rules (Prometheus Rule Groups)](#alerting-rules-prometheus-rule-groups)
+    - [API Documentation Reference](#api-documentation-reference)
+      - [Chat WebSocket API](#chat-websocket-api)
+      - [Playout and Delivery REST API](#playout-and-delivery-rest-api)
+      - [Admin REST API](#admin-rest-api)
+    - [Cloudflare Configuration Reference](#cloudflare-configuration-reference)
+      - [DNS and Zone Routing](#dns-and-zone-routing)
+      - [Cache Rules Baseline](#cache-rules-baseline)
+      - [Edge Security and Controls](#edge-security-and-controls)
+      - [Worker and Header Policy](#worker-and-header-policy)
+      - [Operations and Validation](#operations-and-validation)
+    - [Security \& Moderation](#security--moderation)
+      - [Transport and Edge Protection](#transport-and-edge-protection)
+      - [Reverse Proxy Enforcement (nginx)](#reverse-proxy-enforcement-nginx)
+      - [Admin Authentication and Session Security](#admin-authentication-and-session-security)
+      - [Rate Limiting and Abuse Controls](#rate-limiting-and-abuse-controls)
+      - [CORS and Cross-Origin Behavior](#cors-and-cross-origin-behavior)
+      - [Moderation and Privacy](#moderation-and-privacy)
+    - [Chat](#chat)
+  - [Architecture Decisions](#architecture-decisions)
+  - [Quality Requirements](#quality-requirements)
+    - [Performance Benchmarks and Capacity Planning](#performance-benchmarks-and-capacity-planning)
+      - [Baseline SLO Targets (v1)](#baseline-slo-targets-v1)
+      - [Workload Assumptions](#workload-assumptions)
+      - [Initial Capacity Model](#initial-capacity-model)
+      - [Benchmark Plan](#benchmark-plan)
+      - [Capacity Triggers and Actions](#capacity-triggers-and-actions)
+    - [Scaling Strategy](#scaling-strategy)
+      - [Phase 1: Vertical + Cache-First (Current Baseline)](#phase-1-vertical--cache-first-current-baseline)
+      - [Phase 2: Service Separation](#phase-2-service-separation)
+      - [Phase 3: Multi-Origin Resilience](#phase-3-multi-origin-resilience)
+      - [Phase 4: Regional and Throughput Expansion](#phase-4-regional-and-throughput-expansion)
+      - [Scaling Triggers](#scaling-triggers)
+    - [Disaster Recovery and Backup Procedures](#disaster-recovery-and-backup-procedures)
+      - [Recovery Targets](#recovery-targets)
+      - [Backup Scope](#backup-scope)
+      - [Backup Cadence](#backup-cadence)
+      - [Recovery Runbook (Minimum)](#recovery-runbook-minimum)
+      - [Failure Modes and Strategy](#failure-modes-and-strategy)
+  - [Risks and Technical Debts](#risks-and-technical-debts)
+  - [Glossary](#glossary)
+
+## Companion Documentation
+
+- [API.md](../../API.md) - Implemented WebSocket and REST API reference.
+- [DEPLOYMENT.md](../../DEPLOYMENT.md) - Production deployment and operational runbook.
+- [MONITORING.md](../../MONITORING.md) - Metrics, dashboards, and monitoring troubleshooting.
+- [SECURITY.md](../../SECURITY.md) - Security model, controls, and hardening baseline.
 
 ## Introduction and Goals
 
@@ -107,13 +182,6 @@ flowchart TD
     Chat --> VPS
     VPS -->|Proxy / Static| Pages
     CDN -->|Origin Pull on Miss| R2
-
-    classDef cloud fill:#f0f0ff,stroke:#4263eb
-    classDef vps fill:#f0fff0,stroke:#2e7d32
-    classDef user fill:#fff0f0,stroke:#c62828
-    class Cloudflare,CDN,Pages,R2 cloud
-    class VPS,Playout,Chat vps
-    class Viewers,Admins user
 ```
 
 **External Interfaces**:
@@ -196,9 +264,116 @@ graph TD
 
 Detailed black-box descriptions, level-2/3 views, and code locations are in `adr/ADR-001.md` and future implementation ADRs.
 
-### Level 2 & 3
+### Level 2
 
-Deferred to implementation (see ADR for component responsibilities, interfaces, quality attributes, and risks). Playout enforces normalization; Delivery layer focuses on cache rules and immutable naming.
+Detailed component diagram with code locations and persistence.
+
+```mermaid
+graph TB
+    subgraph "Cloudflare Edge"
+        CF[CDN + WAF<br/>Cache Rules]
+        R2[R2 Bucket<br/>media + HLS]
+        PAGES[Pages<br/>SPA hosting]
+    end
+
+    subgraph "Docker Host (Hetzner CX22)"
+        NGINX[nginx<br/>:80/:443<br/>proxy + auth]
+        CHAT[chat service<br/>:3000<br/>Go + gorilla/websocket]
+        PLAYOUT[playout service<br/>:8081<br/>Go + FFmpeg]
+        REDIS[Redis 7<br/>:6379<br/>presence/rate/pubsub]
+        DB[PostgreSQL 15<br/>:5432<br/>chat history/moderation]
+    end
+
+    subgraph "External"
+        VIEWER[Viewer Browser<br/>hls.js + WebSocket]
+        ADMIN[Admin Browser<br/>SPA + uploads]
+    end
+
+    VIEWER -->|HTTPS| CF
+    VIEWER -->|WSS| NGINX
+    ADMIN -->|HTTPS| CF
+    CF --> NGINX
+    NGINX --> CHAT
+    NGINX --> PLAYOUT
+    NGINX -->|/hls/*| R2
+    CHAT --> REDIS
+    CHAT --> DB
+    PLAYOUT --> R2
+    PLAYOUT -->|reads| R2
+```
+
+#### Playout Service (`backend/playout/src/playlist.go`)
+
+- **Role**: Continuous HLS encoding loop using FFmpeg concat demuxer
+- **Input**: `data/playlist/playlist.txt` — ordered list of MP4 file paths
+- **Output**: HLS segments (`.ts`) + live manifest (`.m3u8`) written to `data/hls/`, mirrored to R2
+- **Resilience**: Restart counter (>5/60s → activate slate), Prometheus metrics on port 8081
+- **Validation**: ffprobe gate on all ingested files (codec, fps, resolution, keyframe interval)
+
+#### Chat Service (`backend/chat/src/main.go`)
+
+- **Role**: WebSocket chat with rooms, DMs, moderation, admin API
+- **Persistence**: PostgreSQL 15 via GORM (messages, moderation logs, media metadata). SQLite for dev fallback
+- **Redis**: Presence tracking, rate limiting, pub/sub for multi-instance fan-out
+- **Auth**: Session-cookie admin auth with Redis-backed expiry
+- **Metrics**: Connected clients, stored messages, DMs, moderation actions on `/metrics`
+
+#### Frontend SPA (`frontend/`)
+
+- **Viewer**: `src/main.ts` — hls.js player, WebSocket chat, presence indicators, schedule overlay
+- **Admin**: `src/admin.ts` — 9 dynamic tabs (dashboard, upload, playlist, schedule, moderation, chat-log, users, analytics, system)
+- **Build**: Vite → static output in `frontend/dist/`
+
+#### Reverse Proxy (`infrastructure/nginx/nginx.conf`)
+
+- auth_request gate on `/admin` and `/api/admin`
+- WebSocket upgrade for `/ws`
+- HLS CORS headers + OPTIONS preflight
+- `/health` JSON endpoint, `/nginx-status` stub_status
+
+### Level 3
+
+Module-level breakdown per service.
+
+#### Chat Service Modules
+
+| Module                 | File/Lines                                                     | Responsibility                                                                           |
+| ---------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Connection Manager** | `main.go` (hub, clients map)                                   | Track active WebSocket connections per room, fan-out messages                            |
+| **Message Parser**     | `main.go` (readPump, handleMessage)                            | Parse JSON envelope `{type, room?, ...}`, validate fields, route to handler              |
+| **Room Registry**      | `main.go` (rooms map, room broadcasts)                         | Map room name → client set, handle join/leave/close                                      |
+| **DM Router**          | `main.go` (handleDirectMessage)                                | Resolve target user in clients map, deliver private message                              |
+| **Persistence Layer**  | `main.go` (GORM models: Message, DirectMessage, ModerationLog) | Store/retrieve chat messages, DMs, moderation events                                     |
+| **Redis Subsystem**    | `main.go` (redisClient, rate limiting, pub/sub, presence)      | INCR+EXPIRE rate limit, SETEX presence, PSUBSCRIBE room fan-out                          |
+| **Auth Handler**       | `main.go` (handleAdminLogin, adminAuthMiddleware)              | Session cookie creation/validation, login rate limiting                                  |
+| **Admin API Router**   | `main.go` (handleAdmin\*)                                      | Upload, playlist CRUD, schedule overrides, moderation actions, analytics, system summary |
+| **Metrics Exporter**   | `main.go` (prometheus.MustRegister)                            | Expose connected_clients, messages_total, dms_total, moderation_actions, redis_up        |
+
+#### Playout Service Modules
+
+| Module               | File/Lines                                     | Responsibility                                                     |
+| -------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
+| **Playlist Parser**  | `playlist.go` (parsePlaylist)                  | Read `playlist.txt`, skip comments/blank lines, resolve file paths |
+| **FFmpeg Manager**   | `playlist.go` (runPlayout, restart logic)      | Spawn/monitor FFmpeg concat process, restart on crash              |
+| **Slate Controller** | `playlist.go` (activateSlate, deactivateSlate) | Switch output to slate loop on excessive failures                  |
+| **R2 Sync**          | `playlist.go` (syncToR2)                       | Upload HLS segments + manifest to R2 bucket                        |
+| **Health Endpoint**  | `playlist.go` (healthHandler)                  | `/health` → JSON with mode, segment count, uptime                  |
+| **Metrics Exporter** | `playlist.go` (prometheus)                     | Expose restarts_total, mode (live/slate)                           |
+
+#### Frontend Modules
+
+| Module                  | File                                            | Responsibility                                                    |
+| ----------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
+| **HLS Player**          | `src/main.ts`                                   | hls.js initialization, attach to video element, error recovery    |
+| **WebSocket Client**    | `src/main.ts`                                   | Connect/disconnect, parse envelope, dispatch to UI handlers       |
+| **Chat UI**             | `src/main.ts`                                   | Message list rendering, room tabs, DM panel, presence dots        |
+| **Schedule Overlay**    | `src/main.ts`                                   | Poll `/api/schedule`, render current/next program                 |
+| **Admin Router**        | `src/admin.ts`                                  | Tab-based navigation, dynamic page loading                        |
+| **Upload Manager**      | `src/admin.ts`                                  | Multipart upload with chunk progress, ffprobe validation feedback |
+| **Playlist Editor**     | `src/admin.ts`                                  | Drag-reorder, add/remove items, save to `/api/admin/playlist`     |
+| **Moderation Panel**    | `src/admin.ts` + `public/admin/moderation.html` | Inline mute/ban, action log viewer                                |
+| **Analytics Dashboard** | `src/admin.ts` + `public/admin/analytics.html`  | Message counts, top rooms, moderation stats                       |
+| **System Config**       | `src/admin.ts` + `public/admin/system.html`     | Service health, config metadata, restart buttons                  |
 
 ## Runtime View
 
@@ -217,6 +392,58 @@ Notable aspects: Manifest freshness ensures all viewers stay on same timeline; c
 
 ## Deployment View
 
+### CI/CD Pipeline Architecture
+
+The deployment follows a two-stage pipeline: **CI builds and pushes images**, then **CD pulls and deploys** them. Currently targeting the **test lab** (192.168.88.40). Production Hetzner VPS is planned but not yet provisioned — the same pipeline will deploy there by changing `DOCKER_HOST`.
+
+```mermaid
+flowchart LR
+    subgraph "Gitea Actions"
+        CI[CI Workflow<br/>Build + Push Images]
+        CD[CD Workflow<br/>Pull + Deploy]
+    end
+    subgraph "Gitea Container Registry"
+        REGISTRY[git.allucanget.biz<br/>playout:latest<br/>chat:latest<br/>nginx:latest]
+    end
+    subgraph "Test Lab Host (192.168.88.40) — Production Hetzner TBD"
+        DOCKER[Docker Engine<br/>via TCP :2375]
+        PLAYOUT[linearvoid-playout]
+        CHAT[linearvoid-chat]
+        NGINX[linearvoid-nginx]
+        REDIS[linearvoid-redis]
+        DB[linearvoid-db]
+        PROM[linearvoid-prometheus]
+        GRAF[linearvoid-grafana]
+    end
+
+    CI -->|push| REGISTRY
+    REGISTRY -->|pull| CD
+    CD -->|deploy via DOCKER_HOST| DOCKER
+    DOCKER --> PLAYOUT
+    DOCKER --> CHAT
+    DOCKER --> NGINX
+    DOCKER --> REDIS
+    DOCKER --> DB
+    DOCKER --> PROM
+    DOCKER --> GRAF
+```
+
+**Pipeline Sequence:**
+
+1. **CI Workflow** (`.gitea/workflows/ci.yml`):
+   - Triggers on `push` to `main` or `pull_request`
+   - Runs `test` job: frontend lint/build, Go validation, `docker compose build`
+   - Runs `docker` job (after `test` passes, only on `main` push):
+     - Builds `playout`, `chat`, `nginx` images with Buildx
+     - Pushes to Gitea Container Registry with `main` and `latest` tags
+2. **CD Workflow** (`.gitea/workflows/cd.yml`):
+   - Triggers on `workflow_run` when CI completes successfully, or manually via `workflow_dispatch`
+   - Pulls latest images from registry
+   - Generates `.env` from secrets
+   - Seeds Prometheus config into named volume
+   - Deploys via `docker compose -f docker-compose.prod.yml up -d` to remote host (`192.168.88.40:2375` — test lab; switch to Hetzner IP for production)
+   - Runs health checks with retry logic for playout initialization
+
 ### Infrastructure Level 1
 
 **Overview Diagram**: See Mermaid in Building Block section (VPS + Cloudflare R2/Pages/CDN).
@@ -233,7 +460,7 @@ Notable aspects: Manifest freshness ensures all viewers stay on same timeline; c
 
 ### Infrastructure Level 2
 
-**Hetzner VPS**: Runs playout (FFmpeg/MediaMTX), chat backend, Nginx. Monitoring via dashboards + UptimeRobot. Backups to R2.
+**Hetzner VPS (planned):** Will run playout (FFmpeg/MediaMTX), chat backend, Nginx. Monitoring via dashboards + UptimeRobot. Backups to R2. Currently test lab (`192.168.88.40`) serves this role. Production Hetzner instance not yet provisioned — see Production Deployment section in [`DEPLOYMENT.md`](../../DEPLOYMENT.md).
 
 **Cloudflare Layer**:
 
@@ -252,15 +479,224 @@ Immutable segment naming + targeted Cloudflare Cache Rules + R2 ($0 egress) = ne
 
 ### Video Normalization & Playout
 
-All source assets must be pre-normalized (H.264/AVC, AAC-LC, constant 30 fps, 2s keyframe interval, CRF). Prevents glitches during continuous concat. FFmpeg `-c copy` preferred for efficiency.
+All source assets must be pre-normalized before they are accepted into production playlists. This prevents decode resets, timestamp drift, and audio/video discontinuities during continuous concat playout.
+
+#### Required Source Profile (Linear Void v1)
+
+| Field                   | Required Value                     | Notes                                                   |
+| ----------------------- | ---------------------------------- | ------------------------------------------------------- |
+| Container               | MP4                                | Single-video-asset input format                         |
+| Video codec             | H.264/AVC (`libx264`)              | Baseline delivery codec for broad compatibility         |
+| Audio codec             | AAC-LC                             | Stereo preferred                                        |
+| Resolution              | 1280x720 or 1920x1080              | Keep single resolution per playlist block when possible |
+| Framerate               | Constant 30 fps (`-r 30`)          | Variable frame rate content must be normalized          |
+| GOP / keyframe interval | 2 seconds (`-g 60 -keyint_min 60`) | Matches HLS segment boundaries better                   |
+| Pixel format            | `yuv420p`                          | Browser compatibility baseline                          |
+| Audio sample rate       | 48 kHz                             | Stable timing for concat playout                        |
+| Audio bitrate           | 128k-192k                          | Predictable quality envelope                            |
+
+#### Reference Normalization Command
+
+```bash
+ffmpeg -i input.mov \
+  -c:v libx264 -preset medium -crf 21 \
+  -r 30 -g 60 -keyint_min 60 -sc_threshold 0 \
+  -pix_fmt yuv420p \
+  -c:a aac -b:a 160k -ar 48000 -ac 2 \
+  -movflags +faststart \
+  output-normalized.mp4
+```
+
+#### Verification Gate (ffprobe)
+
+- Validate codec, fps, resolution, and keyframe cadence before upload acceptance.
+- Reject non-conforming files from admin ingest with actionable error feedback.
+- Keep verification logic aligned with runtime playout assumptions to preserve `-c copy` efficiency where possible.
 
 ### Monitoring & Resilience
 
-Alert on no new segment (>30–60s), low cache hits, high R2 ops, WebSocket errors. Maintain emergency slate, auto-restart, weekly backups, incident runbook.
+Linear Void uses a two-layer monitoring model:
+
+1. **Application layer (chat + platform health)** via Prometheus metrics and a lightweight Grafana dashboard.
+2. **Infrastructure/runtime layer (Prometheus self-observability, TSDB, query engine, Go runtime)** via a detailed Grafana dashboard.
+
+#### Prometheus Baseline
+
+- Config file: `monitoring/prometheus/prometheus.yml`
+- Default scrape interval: `15s`
+- Current scrape jobs: `chat` -> `chat:3000`, `prometheus` -> `prometheus:9090`.
+
+Recommended next-step scrape targets (if/when exporters are introduced):
+
+- `nginx` (via nginx-exporter)
+- `redis` (via redis-exporter)
+- `postgres` (via postgres-exporter)
+- `node` (via node-exporter)
+
+#### Grafana Dashboards
+
+- `monitoring/grafana/dashboard.json` (Linear Void app metrics: connected clients, messages, moderation actions, Redis reachability, admin sessions, scrape health).
+- `monitoring/grafana/dashboards/dashboard.json` (Prometheus operational visibility: status, uptime, CPU/memory, TSDB ingestion/churn/errors, HTTP latencies, query load, GC/scheduler).
+
+Use the app dashboard for service-level behavior and the Prometheus overview dashboard for platform diagnostics and capacity planning.
+
+#### Alerting Rules (Prometheus Rule Groups)
+
+Define alert rules as grouped policies (for example in `monitoring/prometheus/alerts.yml`) and include them from `prometheus.yml`.
+
+Minimum recommended alert set:
+
+- **Availability**
+  `up{job="chat"} == 0` for `2m`; `up{job="prometheus"} == 0` for `2m`.
+- **Chat service health**
+  `linearvoid_chat_redis_up == 0` for `2m`; sudden disconnect spike / connected clients collapse.
+- **Playout continuity**
+  No HLS segment progression for `30-60s` (from playout-specific metric when available).
+- **Prometheus capacity and ingestion health**
+  Sustained growth in `prometheus_tsdb_wal_writes_failed_total` or `prometheus_tsdb_compactions_failed_total`, abnormal jump in `prometheus_tsdb_out_of_order_samples_total`, and high `prometheus_engine_queries` near concurrent limit.
+- **Latency and user-impact**
+  Elevated p99 handler latency from `prometheus_http_request_duration_seconds_bucket` and elevated p99 query execution latency from `prometheus_engine_query_duration_histogram_seconds_bucket`.
+
+Route warning/critical severities to the team channel and keep runbook links attached to each alert definition.
+
+Operational resilience baseline:
+
+- Emergency slate fallback for playout failure.
+- Auto-restart policies for playout/chat/nginx containers.
+- Weekly backup and restore drills for stateful data (`data/chat`, playlist metadata, Postgres).
+- Incident runbook with triage order: edge reachability -> origin health -> playout progression -> chat connectivity -> data-plane dependencies.
+
+### API Documentation Reference
+
+Linear Void currently exposes three operational API surfaces. The canonical detailed contract should live in `API.md`, while this section provides the architecture-level map.
+
+#### Chat WebSocket API
+
+- Endpoint: `/ws`
+- Transport: `wss://` in production, `ws://` locally
+- Query parameters:
+  - `username`
+  - `room`
+- Message envelope (typical):
+  - `room`
+  - `username`
+  - `text`
+  - `type` (`public`, `private`, `system`)
+- Responsibilities:
+  - room fan-out
+  - private DM channel routing
+  - moderation command handling
+  - rate limiting and presence integration
+
+#### Playout and Delivery REST API
+
+- Health endpoints:
+  - playout health (`/health` on playout service)
+  - edge/origin health (`/health` via nginx)
+- Stream delivery:
+  - HLS manifest and segment path namespace under `/hls/`
+- Responsibilities:
+  - expose liveness for orchestration and monitoring
+  - provide stable HLS path contract for viewer and CDN
+
+#### Admin REST API
+
+- Auth/session:
+  - `/api/admin/login`
+  - `/api/admin/logout`
+  - `/api/admin/session`
+- Operational/admin domains:
+  - overview, analytics, users, moderation, schedule, playlist, media
+- Media upload domain:
+  - `/api/admin/media/uploads` (init/resume)
+  - `/api/admin/media/uploads/{uploadId}/chunk`
+  - `/api/admin/media/uploads/{uploadId}/complete`
+- Responsibilities:
+  - protected control plane for operator workflows
+  - media metadata + upload orchestration
+  - moderation/audit and system status management
+
+### Cloudflare Configuration Reference
+
+Cloudflare is part of the production control plane, not only a CDN edge. The following configuration set is required to maintain cost, latency, and reliability targets.
+
+#### DNS and Zone Routing
+
+- `linearvoid.tv` -> application origin (nginx)
+- `www.linearvoid.tv` -> redirect to apex
+- `media.linearvoid.tv` -> media domain for HLS/object delivery when split-domain mode is enabled
+
+#### Cache Rules Baseline
+
+- HLS segments (`.ts`, `.m4s`):
+  - Cache Everything
+  - long TTL (immutable)
+  - respect immutable semantics
+- Manifests (`.m3u8`):
+  - short TTL (1-10s)
+  - revalidation-friendly policy for timeline freshness
+
+#### Edge Security and Controls
+
+- Enforce HTTPS/WSS and redirect HTTP to HTTPS.
+- Enable WAF baseline protections for common web exploits.
+- Apply rate limits for abusive request patterns (especially auth/admin paths).
+- Keep origin exposure minimized (prefer Cloudflare-only public ingress where feasible).
+
+#### Worker and Header Policy
+
+- Use Worker logic for immutable cache headers and request normalization where cache rules alone are insufficient.
+- Keep CORS behavior explicit for HLS resources to support browser playback.
+
+#### Operations and Validation
+
+- Validate cache behavior after deployment:
+  - expected cache status progression (MISS -> HIT)
+  - manifest freshness under active playout
+- Track edge metrics and adjust:
+  - cache hit ratio
+  - request volume and error rates
+  - ToS/cost posture for sustained traffic profiles
 
 ### Security & Moderation
 
-HTTPS/WSS only, strict CORS, Cloudflare WAF, authenticated admin paths, rate limiting, immutable moderation log. Private DMs not E2EE by default.
+Security is split between edge controls (Cloudflare), reverse proxy controls (nginx), and application controls (chat/admin backend).
+
+#### Transport and Edge Protection
+
+- Public traffic uses HTTPS/WSS at the edge.
+- Cloudflare WAF and rate limiting are part of the baseline (see `infrastructure/cloudflare/cache-rules.md`).
+- Cloudflare Worker can enforce immutable cache headers for segment paths (`infrastructure/cloudflare/worker.js`).
+
+#### Reverse Proxy Enforcement (nginx)
+
+- Admin UI and admin API paths are protected by `auth_request` before reaching backend handlers (`/admin/`, `/api/admin/`).
+- Unauthorized admin UI requests are redirected to `/admin/login/`.
+- Unauthorized admin API requests return JSON `401` from a dedicated location handler.
+- WebSocket upgrade headers are explicitly forwarded for `/ws`.
+
+#### Admin Authentication and Session Security
+
+- Admin authentication is cookie-session based (`linearvoid_admin_session`).
+- Session cookie controls in backend include `HttpOnly`, `SameSite=Strict`, and `Secure` when request is HTTPS (derived from TLS or `X-Forwarded-Proto`).
+- Session expiration is enforced server-side.
+
+#### Rate Limiting and Abuse Controls
+
+- Chat message rate limiting uses Redis `INCR + EXPIRE` windowing.
+- Current baseline in chat handler: `>10` messages within `10s` triggers a user-facing throttle response.
+- If Redis is unavailable, presence/rate-limit features degrade gracefully (warning logged; core chat remains available).
+
+#### CORS and Cross-Origin Behavior
+
+- HLS endpoints exposed by nginx include explicit `Access-Control-Allow-Origin: *` for player compatibility.
+- Admin/authenticated routes are expected to run same-origin behind nginx auth gates.
+
+#### Moderation and Privacy
+
+- Moderation commands (`/mod`, `/mute`, `/ban`) are handled in backend chat flow and persisted through chat storage paths.
+- Private DMs are application-level private channels, not end-to-end encrypted in current architecture.
+- Moderation and audit retention policies should be formalized in runbook/ops docs as part of production hardening.
 
 ### Chat
 
@@ -295,6 +731,147 @@ These ADRs together form the canonical decision log.
 
 See **Quality Goals** table in the Introduction section. Primary scenarios focus on cost (near-zero egress), availability (auto-restart + fallback), scalability (edge caching), and usability (synchronized player + responsive chat).
 
+### Performance Benchmarks and Capacity Planning
+
+#### Baseline SLO Targets (v1)
+
+- Playback startup: target < 4s after first manifest request on warm cache.
+- Steady-state playback: no segment starvation during normal operation.
+- End-to-end HLS latency: expected 15-35s (standard HLS trade-off).
+- Chat delivery latency: p95 < 500ms inside same region under normal load.
+- Admin page responsiveness: p95 API response < 1s for common read operations.
+
+#### Workload Assumptions
+
+- Primary audience in US; origin in US-East.
+- Edge cache serves most segment traffic; origin handles manifest churn and cache misses.
+- Chat traffic scales with concurrent viewers but remains low-bandwidth compared to video.
+
+#### Initial Capacity Model
+
+- Video bitrate envelopes (from ADR-001):
+  - 720p30: ~2.6-4.2 Mbps total with audio.
+  - 1080p30: ~5.1-8.2 Mbps total with audio.
+- Storage planning for 48h rolling library:
+  - 720p30: ~57-90 GB raw (allocate ~80-110 GB with headroom).
+  - 1080p30: ~110-175 GB raw (allocate ~130-180 GB with headroom).
+- Cost behavior:
+  - Viewer scale is mostly constrained by cache efficiency and request volume, not by direct origin egress.
+
+#### Benchmark Plan
+
+- Playback path:
+  - Measure time-to-first-frame and rebuffer events from multiple US regions.
+  - Track manifest freshness and segment availability at edge.
+- Chat path:
+  - Load-test concurrent websocket connections and message fan-out.
+  - Measure p50/p95 send-to-receive latency and Redis fallback behavior.
+- Admin/API path:
+  - Benchmark playlist/system endpoints for p95 latency and error rate.
+- Platform path:
+  - Observe TSDB ingestion, query p99, and GC pause behavior in Grafana.
+
+#### Capacity Triggers and Actions
+
+- Trigger: sustained viewer growth with rising cache-miss ratio.
+  - Action: tighten cache policy, enable/verify Tiered Cache, review manifest TTL.
+- Trigger: chat p95 latency drift or websocket error growth.
+  - Action: scale chat service, tune Redis, separate noisy moderation workloads.
+- Trigger: Prometheus WAL/compaction failures or query saturation.
+  - Action: tune retention/cardinality, increase resources, split dashboards/queries.
+- Trigger: origin CPU/memory pressure on playout host.
+  - Action: optimize FFmpeg profile, isolate services, add secondary origin.
+
+### Scaling Strategy
+
+Scaling is designed to preserve cost efficiency first, then increase throughput and resilience in controlled phases.
+
+#### Phase 1: Vertical + Cache-First (Current Baseline)
+
+- Single primary origin in US-East with strong Cloudflare edge caching.
+- Optimize segment immutability and manifest TTL before adding infrastructure.
+- Scale compute vertically when CPU/memory pressure appears on playout/chat host.
+
+#### Phase 2: Service Separation
+
+- Split playout, chat, and observability workloads across dedicated nodes/VMs.
+- Isolate noisy workloads (analytics, heavy admin tasks) from latency-sensitive chat paths.
+- Introduce managed PostgreSQL/Redis or dedicated state nodes where operationally justified.
+
+#### Phase 3: Multi-Origin Resilience
+
+- Add warm standby or active-secondary origin.
+- Use health-aware DNS/origin failover strategy.
+- Keep HLS path and cache contract stable so viewer impact during failover is minimized.
+
+#### Phase 4: Regional and Throughput Expansion
+
+- Add additional origin region only when audience distribution and latency justify it.
+- Keep chat affinity strategy explicit (regional routing, state replication considerations).
+- Continuously evaluate cache miss economics vs additional origin complexity.
+
+#### Scaling Triggers
+
+- Rising cache miss ratio with sustained traffic growth.
+- Chat p95/p99 latency drift or websocket error growth.
+- Persistent origin resource saturation despite optimization.
+- Increased blast-radius concerns from single-host dependency.
+
+### Disaster Recovery and Backup Procedures
+
+#### Recovery Targets
+
+- RPO target: <= 24h for chat/moderation/admin metadata.
+- RTO target: <= 60 minutes for restoring baseline streaming + chat operations.
+
+#### Backup Scope
+
+- Persistent service volumes:
+  - Postgres data (`postgres-data` volume).
+  - Redis append-only persistence (`redis-data` volume) where enabled.
+  - Prometheus long-term TSDB (`prometheus-data` volume) if historical metrics retention is required.
+  - Grafana state (`grafana-data` volume) if dashboards/users are managed in-instance.
+- Host-mounted state directories:
+  - `data/chat`
+  - `data/playlist`
+  - `data/media` (authoritative source may be R2/object storage)
+  - `data/hls` (optional; can be regenerated by playout)
+- Configuration and infra source of truth:
+  - Compose files, nginx config, monitoring configs, and environment template.
+
+#### Backup Cadence
+
+- Daily logical Postgres backups (plus weekly full snapshot).
+- Daily sync of chat/playlist state directories.
+- Weekly integrity check by restoring backups into an isolated environment.
+- Retention policy baseline:
+  - Daily backups: 14 days
+  - Weekly backups: 8 weeks
+  - Monthly backups: 6 months
+
+#### Recovery Runbook (Minimum)
+
+1. Restore infrastructure configuration (compose, nginx, env, monitoring config).
+2. Restore Postgres and Redis persisted state.
+3. Restore `data/playlist` and chat persistence directories.
+4. Rehydrate media from authoritative object storage if local media is missing.
+5. Start stack and validate in order:
+   - `playout` health endpoint
+   - `chat` health endpoint
+   - nginx `/health`
+   - HLS playlist availability
+   - websocket chat connectivity
+6. Verify admin authentication and moderation audit visibility.
+7. Announce recovery and continue elevated monitoring for at least one playlist cycle.
+
+#### Failure Modes and Strategy
+
+- Single-host loss: redeploy stack on standby host, restore data backups, repoint DNS/edge origin.
+- Storage corruption: restore last known-good snapshot and replay latest logical backups.
+- Partial service failure: replace only impacted service and restore scoped data (for example Postgres only).
+
+Document and rehearse this runbook quarterly; recovery that is not exercised is not reliable.
+
 ## Risks and Technical Debts
 
 - Cloudflare ToS risk for heavy video on free tier (use R2 path; fallback to BunnyCDN if challenged).
@@ -322,162 +899,3 @@ See **Quality Goals** table in the Introduction section. Primary scenarios focus
 | Tiered Cache      | Cloudflare feature reducing origin requests by checking upper-tier caches first.           |
 
 **References**: Cloudflare R2/Cache docs, MediaMTX/SRS/FFmpeg HLS guides, Hetzner pricing, hls.js documentation, standard video bitrate calculators. All original root `ADR-001-*.md` files have been consolidated and can be archived/deleted.
-
-### Whitebox Overall System
-
-**_\<Overview Diagram\>_**
-
-Motivation
-
-: _\<text explanation\>_
-
-Contained Building Blocks
-
-: _\<Description of contained building block (black boxes)\>_
-
-Important Interfaces
-
-: _\<Description of important interfaces\>_
-
-#### \<Name black box 1\>
-
-_\<Purpose/Responsibility\>_
-
-_\<Interface(s)\>_
-
-_\<(Optional) Quality/Performance Characteristics\>_
-
-_\<(Optional) Directory/File Location\>_
-
-_\<(Optional) Fulfilled Requirements\>_
-
-_\<(optional) Open Issues/Problems/Risks\>_
-
-#### \<Name black box 2\>
-
-_\<black box template\>_
-
-#### \<Name black box n\>
-
-_\<black box template\>_
-
-#### \<Name interface 1\>
-
-...​
-
-#### \<Name interface m\>
-
-### Level 2
-
-#### White Box _\<building block 1\>_
-
-_\<white box template\>_
-
-#### White Box _\<building block 2\>_
-
-_\<white box template\>_
-
-...​
-
-#### White Box _\<building block m\>_
-
-_\<white box template\>_
-
-### Level 3
-
-#### White Box \<\_building block x.1\_\>
-
-_\<white box template\>_
-
-#### White Box \<\_building block x.2\_\>
-
-_\<white box template\>_
-
-#### White Box \<\_building block y.1\_\>
-
-_\<white box template\>_
-
-## Runtime View
-
-### \<Runtime Scenario 1\>
-
-- _\<insert runtime diagram or textual description of the scenario\>_
-
-- _\<insert description of the notable aspects of the interactions
-  between the building block instances depicted in this diagram.\>_
-
-### \<Runtime Scenario 2\>
-
-### ...​
-
-### \<Runtime Scenario n\>
-
-## Deployment View
-
-### Infrastructure Level 1
-
-**_\<Overview Diagram\>_**
-
-Motivation
-
-: _\<explanation in text form\>_
-
-Quality and/or Performance Features
-
-: _\<explanation in text form\>_
-
-Mapping of Building Blocks to Infrastructure
-
-: _\<description of the mapping\>_
-
-### Infrastructure Level 2
-
-#### _\<Infrastructure Element 1\>_
-
-_\<diagram + explanation\>_
-
-#### _\<Infrastructure Element 2\>_
-
-_\<diagram + explanation\>_
-
-...​
-
-#### _\<Infrastructure Element n\>_
-
-_\<diagram + explanation\>_
-
-## Cross-cutting Concepts
-
-### _\<Concept 1\>_
-
-_\<explanation\>_
-
-### _\<Concept 2\>_
-
-_\<explanation\>_
-
-...​
-
-### _\<Concept n\>_
-
-_\<explanation\>_
-
-## Architecture Decisions
-
-## Quality Requirements
-
-### Quality Requirements Overview
-
-### Quality Scenarios
-
-## Risks and Technical Debts
-
-## Glossary
-
-+----------------------+-----------------------------------------------+
-| Term | Definition |
-+======================+===============================================+
-| _\<Term-1\>_ | _\<definition-1\>_ |
-+----------------------+-----------------------------------------------+
-| _\<Term-2\>_ | _\<definition-2\>_ |
-+----------------------+-----------------------------------------------+

docs/architecture/adr/ADR-004-admin-video.md

@@ -60,8 +60,6 @@ Create a dedicated **admin web interface** in a new `frontend/admin/` directory
 - Integration with existing playout service and R2 keeps the architecture consistent.
 - Admin actions will be fully auditable, paving the way for ADR-005 (moderation and user management).
 
-This decision was planned in `TODO.md` before implementation, per AGENTS.md.
-
 ## Consequences
 
 **Positive**:

docs/architecture/adr/ADR-005-admin-moderation-analytics.md

@@ -59,8 +59,6 @@ Extend the admin interface started in ADR-004 with additional protected sections
 - Leveraging Prometheus/Grafana for analytics avoids duplicating metrics collection.
 - Immutable audit logging supports future compliance and moderation review (key requirement for a public chat system).
 
-This ADR was planned in `TODO.md` before any implementation, per AGENTS.md.
-
 ## Consequences
 
 **Positive**:
@@ -92,8 +90,6 @@ This ADR was planned in `TODO.md` before any implementation, per AGENTS.md.
 7. Update authentication middleware and tests.
 8. Document API contracts and update `docker-compose.yml` to expose the admin interface securely.
 
-**Next Steps**: After both admin ADRs are complete, move to implementation of the Playout Service (highest priority in the core modules section of TODO.md).
-
 ## References
 
 - ADR-001: Chat features, moderation requirements, monitoring needs.

docs/architecture/adr/ADR-006-data-storage.md

@@ -1,7 +1,7 @@
 # ADR-006: Data Storage Strategy (SQLite vs PostgreSQL)
 
-**Status:** Proposed  
+**Status:** Accepted  
-**Date:** 2026-08-02  
+**Date:** 2026-08-04  
 **Author:** AI Assistant (following AGENTS.md, ADR-002, ADR-003, ADR-004, ADR-005)  
 **Related ADRs:** [ADR-001](./ADR-001.md), [ADR-003](./ADR-003-tech-stack.md), [ADR-005](./ADR-005-admin-moderation-analytics.md), [ADR-007](./ADR-007-redis-usage.md)
 
@@ -12,89 +12,78 @@ The system needs persistent storage for:
 - Chat messages and history (public rooms and private DMs).
 - User accounts, roles, and ban lists.
 - Moderation audit log (immutable record of admin and moderator actions).
-- Playlist metadata and schedule overrides.
+- Playlist and media metadata used by admin flows.
-- System configuration (including Redis settings adjustable via admin UI per ADR-005/ADR-007).
+- System configuration visibility in admin APIs.
 
-From ADR-003 we prefer operational simplicity. ADR-005 requires a robust audit trail. We must decide between **SQLite** (embedded, zero-config) and **PostgreSQL** (full-featured, scalable) and document how the admin interface can view and adjust storage-related configuration.
+The codebase now ships with a PostgreSQL service in Docker Compose (`db`) and chat is configured with a PostgreSQL `DATABASE_URL` by default. The backend still supports SQLite for optional local fallback, but the deployed and compose-default path is PostgreSQL.
 
 ## Decision Drivers
 
-1. **Operational Simplicity** – Minimize infrastructure (no separate DB server for SQLite).
+1. **Implemented Reality** - Docker Compose already provisions PostgreSQL and chat depends on it.
-2. **Performance & Concurrency** – Chat and moderation may have high write volume.
+2. **Concurrency & Throughput** - Chat, moderation, and media metadata writes require stronger concurrent write behavior.
-3. **Backup and Recovery** – Easy point-in-time recovery and replication.
+3. **Operational Traceability** - Structured backups, service health checks, and persistent volume management are already in place for PostgreSQL.
-4. **Admin Capabilities** – Admin UI must be able to view storage stats, run vacuum/analyze, and switch between SQLite and PostgreSQL (with migration path).
+4. **Admin Growth** - Upcoming admin features (media CRUD, analytics, moderation tooling) benefit from relational querying and indexing.
-5. **Auditability** – Moderation log must be immutable and queryable.
+5. **Fallback Simplicity** - Keep SQLite support for lightweight local or recovery scenarios without blocking developer workflows.
-6. **Cost** – Avoid managed database costs during early stages.
 
 ## Decision
 
-**Primary storage for v1: SQLite** (embedded in the chat and admin services).
+**Primary storage for current implementation: PostgreSQL (Docker Compose `db` service).**
 
-**Migration Path**: Provide a clear upgrade path to PostgreSQL when concurrency or replication needs exceed SQLite capabilities (target v2 or when concurrent users > 500).
+**Secondary/Fallback mode:** SQLite remains supported via `DATABASE_URL=sqlite://...` for local-only scenarios.
 
-**Admin Interface Capabilities** (extension of ADR-005):
+**Current Backend Behavior**:
 
-- "System Configuration" tab showing current storage engine, database size, connection stats, and vacuum status.
+- Chat backend (`backend/chat/src/main.go`) resolves `DATABASE_URL` at startup.
-- Buttons to run `VACUUM`, `ANALYZE`, or trigger a backup.
+- `postgres://` or `postgresql://` selects PostgreSQL driver.
-- Configuration form to switch connection string (SQLite file path vs PostgreSQL URL) and restart services gracefully.
+- `sqlite://` selects SQLite driver.
-- Audit log of all configuration changes.
+- Empty `DATABASE_URL` falls back to local `chat.db` for developer convenience.
+- GORM AutoMigrate is used for chat/admin data models.
 
-**Technical Details**:
+**Media Model Decision (Admin UI Feature Track)**:
 
-- Use SQLite with WAL mode for better concurrency.
+- Media metadata is persisted in the same database as messages and moderation logs.
-- Use GORM or sqlx (Go) or Prisma (if Node.js fallback) for ORM/migrations.
+- Physical media files remain on the shared filesystem (`/app/media`, mapped from `data/media`).
-- Store large chat history in a separate table with retention policy (e.g., 30 days).
+- The database is the source of truth for media library metadata and future runtime analytics.
-- Moderation log as an append-only table with triggers for immutability.
-
-**Folder Placement** (per ADR-002):
-
-- Database models and migrations in `backend/shared/db/` or `backend/chat/internal/db/`.
-- Admin UI pages for storage management in `frontend/admin/system/`.
 
 ## Rationale
 
-- SQLite aligns with ADR-003's emphasis on operational simplicity and low resource usage for the initial deployment on a single Hetzner VPS.
+- The repository already operationalizes PostgreSQL in both `docker-compose.yml` and `docker-compose.prod.yml` with persistent storage.
-- It eliminates the need for a separate database container in `docker-compose.yml` during early development.
+- Default environment documentation (`.env.example`, setup docs) already points to PostgreSQL.
-- The admin interface can provide visibility and basic maintenance operations, fulfilling the requirement from the previous TODO plan.
+- This aligns architecture documentation with implemented behavior and avoids drift.
-- PostgreSQL can be introduced later with a migration script when scale demands it (replication, advanced querying, full-text search on chat).
+- Keeping SQLite support preserves local flexibility while avoiding a hard breaking change.
 
 ## Consequences
 
 **Positive**:
 
-- Zero-config database for quick local development and small-scale production.
+- Better write concurrency and query flexibility for chat + admin workloads.
-- Simple backups (just copy the `.db` file).
+- Clear operational model for containerized deployments (health checks, named volume, service dependency).
-- Admin UI can directly manage and monitor storage without external tools.
+- Easier extension for admin analytics and media metadata features.
 
 **Negative / Risks**:
 
-- SQLite has limited concurrency compared to PostgreSQL (WAL mode helps but is not a full replacement).
+- Additional service to operate versus embedded-only SQLite.
-- Large chat history or analytics queries may become slow – plan retention policy and archiving.
+- Misconfigured `DATABASE_URL` can still route to SQLite fallback unintentionally if left empty outside compose.
-- Migration to PostgreSQL will require downtime or dual-write strategy (documented in this ADR).
+- Requires backup/restore procedures for PostgreSQL volume in production runbooks.
 
-**Alternatives Considered**:
+## Alternatives Considered
 
-- PostgreSQL from day one – rejected for added operational complexity (separate service, connection pooling, managed service cost).
+- SQLite-first in production: rejected for current implementation because compose and deployment already run PostgreSQL.
-- Pure key-value store (e.g., BoltDB) – rejected because SQL is better for audit logs and complex moderation queries.
+- PostgreSQL-only with no fallback: rejected to preserve local dev and troubleshooting flexibility.
-- Managed database (Neon, Supabase) – rejected to maintain full self-hosted independence per ADR-001.
+- Managed external PostgreSQL: deferred; self-hosted compose remains the preferred operational model.
 
-## Implementation Plan
+## Implementation Status
 
-1. Create this ADR-006 (done).
+1. ADR updated to match implemented state. Done.
-2. Add SQLite support in `backend/shared/db/` with GORM migrations.
+2. Compose includes PostgreSQL service and persistent volume. Done.
-3. Implement admin UI pages for storage monitoring and configuration (linked to ADR-005).
+3. Chat backend supports PostgreSQL and SQLite based on `DATABASE_URL`. Done.
-4. Add configuration reload capability without full restart where possible.
+4. Media metadata persistence model documented here for Admin UI track. In progress (implementation ongoing).
-5. Write migration script from SQLite to PostgreSQL.
+5. Admin storage observability and operations UI (vacuum/analyze/backup flows). Planned.
-6. Update `docker-compose.yml` to optionally include PostgreSQL.
-7. Add tests for data access patterns and admin configuration changes.
-
-**Next ADR**: ADR-007 (Redis usage and admin configuration capabilities).
 
 ## References
 
 - ADR-001: Chat persistence, moderation log, monitoring requirements.
 - ADR-003: Preference for operational simplicity and Go backend.
-- ADR-005: Admin interface for user management, moderation, and analytics – this ADR extends it with storage and Redis config capabilities.
+- ADR-005: Admin interface for user management, moderation, and analytics.
-- arc42 documentation: Cross-cutting Concepts (data management, monitoring) and Risks & Technical Debts.
+- ADR-007: Redis usage for presence, rate limiting, pub/sub.
-
+- `docker-compose.yml` and `docker-compose.prod.yml` database service definitions.
-This ADR ensures all data storage decisions are documented before code is written, maintaining full traceability.

docs/architecture/adr/ADR-007-redis-usage.md

@@ -95,8 +95,6 @@ We must explicitly document:
 6. Add monitoring (Prometheus exporter) and admin audit logging for configuration changes.
 7. Write tests for rate limiting, presence, and admin configuration flows.
 
-**Next Steps**: After ADR-006 and ADR-007 are reviewed, mark the "Create ADRs for Data Storage, Caching, and Admin Capabilities" section as completed in TODO.md and move it to DONE.md. Then proceed with implementation of the Playout Service.
-
 ## References
 
 - ADR-001: Chat features requiring presence, rate limiting, and pub/sub.

docs/incident-runbook.md

@@ -0,0 +1,164 @@
+# Incident Runbook
+
+Triage order for Linear Void incidents. Work top-to-bottom — each tier depends on the one above.
+
+## Triage Order
+
+1. Edge Reachability (Cloudflare)
+2. Origin Health (VPS/Docker)
+3. Playout Progression (HLS)
+4. Chat Connectivity (WebSocket)
+5. Data-Plane (Redis/DB)
+
+## 1. Edge Reachability (Cloudflare)
+
+**Symptoms:** `linearvoid.tv` not resolving, SSL errors, 5xx from Cloudflare.
+
+```bash
+# Check DNS
+dig linearvoid.tv
+dig www.linearvoid.tv
+
+# Check Cloudflare status
+curl -I https://linearvoid.tv/health
+```
+
+**Common causes:**
+
+- DNS misconfiguration (A record pointing to wrong IP)
+- Cloudflare proxy disabled (grey cloud → origin exposed directly)
+- SSL certificate expired (check Cloudflare dashboard → SSL/TLS)
+- Cloudflare outage → check [https://www.cloudflarestatus.com](https://www.cloudflarestatus.com)
+
+**Mitigation:**
+
+- Verify A record: `linearvoid.tv` → origin IP (proxied, orange cloud)
+- Bypass Cloudflare temporarily: `curl -H "Host: linearvoid.tv" http://<origin-ip>/health`
+
+## 2. Origin Health (VPS/Docker)
+
+**Symptoms:** Cloudflare returns 502/504, containers down.
+
+```bash
+# Remote Docker (test lab)
+docker -H tcp://192.168.88.40:2375 ps
+docker -H tcp://192.168.88.40:2375 logs linearvoid-nginx --tail 50
+
+# Direct health check
+curl http://192.168.88.40/health
+```
+
+**Common causes:**
+
+- Host out of disk space: `df -h`
+- Docker daemon stopped: `systemctl status docker`
+- Container restart loop: `docker ps -a --filter "status=exited"`
+- Resource exhaustion (OOM): `dmesg | grep -i oom`
+
+**Mitigation:**
+
+- Restart stack: `docker compose -f docker-compose.prod.yml up -d`
+- Free disk: `docker system prune -f`
+- Check logs per service: `docker logs linearvoid-<service> --tail 100`
+
+## 3. Playout Progression (HLS)
+
+**Symptoms:** Viewer sees slate or buffering, playlist not advancing.
+
+```bash
+# Check playout health
+curl http://192.168.88.40:8081/health
+# Response includes "mode": "live" or "slate"
+
+# Check HLS output
+curl -I http://192.168.88.40/hls/playlist.m3u8
+ls -la data/hls/
+
+# Check playout logs
+docker logs linearvoid-playout --tail 100
+```
+
+**Common causes:**
+
+- FFmpeg crash → slate fallback active (health shows `degraded`)
+- Playlist file empty/missing: `cat data/playlist/playlist.txt`
+- Media file missing from playlist: `ls data/media/`
+- Disk full → HLS segments can't write
+
+**Mitigation:**
+
+- Verify playlist has valid entries
+- Check media files exist at paths in playlist
+- Restart playout: `docker compose restart playout`
+- Generate demo playlist if empty: see `backend/playout/start-playout.sh`
+
+## 4. Chat Connectivity (WebSocket)
+
+**Symptoms:** Chat not loading, messages not sending, presence broken.
+
+```bash
+# Check chat health
+curl http://192.168.88.40:3000/health
+
+# Test WebSocket
+wscat -c ws://192.168.88.40/ws?username=test&room=main
+
+# Check chat logs
+docker logs linearvoid-chat --tail 100
+```
+
+**Common causes:**
+
+- Redis down → presence/rate-limiting degraded (chat still works)
+- Database down → messages not persisting
+- Port not exposed: `docker port linearvoid-chat`
+
+**Mitigation:**
+
+- Restart chat: `docker compose restart chat`
+- Check Redis: `docker exec linearvoid-redis redis-cli ping`
+- Check DB: `docker exec linearvoid-db pg_isready -U linearvoid`
+- Chat works without Redis (graceful degradation) — check logs for "Redis connection warning"
+
+## 5. Data-Plane (Redis/DB)
+
+**Symptoms:** Chat works but no persistence/presence, admin stats empty.
+
+```bash
+# Redis
+docker exec linearvoid-redis redis-cli ping
+docker exec linearvoid-redis redis-cli info memory
+
+# PostgreSQL
+docker exec linearvoid-db pg_isready -U linearvoid
+docker exec linearvoid-db psql -U linearvoid -c "SELECT count(*) FROM messages;"
+```
+
+**Common causes:**
+
+- Redis OOM (check `maxmemory` setting)
+- PostgreSQL connection limit reached
+- Disk full on volume mount
+
+**Mitigation:**
+
+- Redis: `docker compose restart redis` (AOF persist enabled)
+- PostgreSQL: `docker compose restart db`
+- Restore from backup: see `scripts/verify-backups.sh` for procedure
+
+## Escalation
+
+| Severity | When                                 | Action                                             |
+| -------- | ------------------------------------ | -------------------------------------------------- |
+| Critical | Slate active >30min, complete outage | Trigger DR plan, provision fallback host           |
+| Warning  | Redis down, high CPU >30min          | Investigate during business hours, restart service |
+| Info     | Single service blip                  | Monitor, no action unless recurring                |
+
+## Post-Incident
+
+1. Document timeline in incident channel
+2. Identify root cause
+3. Add prevention to docs if actionable
+4. Update this runbook if new failure mode discovered
+
+**Recovery targets:** RPO ≤24h, RTO ≤60min. Quarterly DR drill: simulate host loss, restore from backup.

docs/marketing/brand-research.md

@@ -0,0 +1,34 @@
+# Brand Research: "Linear Void"
+
+## 1. Trademark & Brand Availability (US Market)
+
+Based on searches of the USPTO database and general web usage, **"Linear Void" is highly viable for a video streaming platform.**
+
+Trademark rights are granted based on specific classes of goods and services. Currently, there are no registered trademarks or active companies using "Linear Void" in the media, broadcasting, or entertainment spaces.
+
+**Existing uses of the phrase (Non-conflicting):**
+
+- **Software / Engineering:** There is a well-known CAD/BIM software plugin called **"LINEAR Void Manager"** developed by a German company (LINEAR GmbH) for architects to plan wall openings (voids) in HVAC design. This falls under structural engineering software and does not conflict with media broadcasting.
+- **Astrophysics / Science:** "Linear void" is a common scientific term used in astrophysics to describe the evolution of underdense regions in the universe (cosmic voids).
+- **Music:** There is an electronic music album titled _Linear Void_. Album titles alone do not typically constitute a conflicting brand trademark.
+
+**Trademark Strategy:** Because your product is a self-managed video channel, you would likely file under **Class 38** (Telecommunications / Video broadcasting) and **Class 41** (Entertainment services / Providing non-downloadable videos). You should have a clear path to registration in the US since no one is using the name in these classes.
+
+## 2. Domain Name
+
+Your custom SPA setup requires a strong, memorable domain. We registered `linearvoid.tv` for this purpose. The `.tv` TLD is widely recognized as a media/entertainment domain, making it ideal for your platform.
+
+## 3. SEO & Market Positioning
+
+**Brand Fit:**
+The name "Linear Void" is an excellent thematic fit for your project. "Linear" directly communicates the 24/7 continuous broadcast format (as opposed to VOD), while "Void" implies an independent, deep-internet, or alternative space—perfect for a platform rejecting third-party ecosystems like YouTube or Twitch.
+
+**Search Engine Optimization (SEO):**
+Currently, searching for "Linear Void" brings up highly niche results (the Revit architecture plugin, medical patents, and astrophysics papers).
+
+- **The Advantage:** You are not competing with any established consumer brands, pop culture entities, or other media companies.
+- **The Execution:** Because the existing search results are so strictly confined to academic and B2B engineering niches, an active video platform with decent metadata, a steady stream of traffic, and proper indexing of your HLS stream titles will very quickly overtake the front page of Google for the term "Linear Void".
+
+## Next Steps
+
+- **USPTO Filing:** Prepare filing an "Intent to Use" (1B) trademark application with the USPTO for "Linear Void" under Classes 38 and 41 to lock in your rights before launch.

frontend/admin/index.html

@@ -5,133 +5,38 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Linear Void Admin</title>
-    <script src="https://cdn.tailwindcss.com"></script>
-    <script src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js" defer></script>
     <link rel="stylesheet" href="../src/style.css" />
 </head>
 
-<body class="bg-slate-950 text-slate-200">
+<body class="admin-body">
-    <div class="flex h-screen" x-data="admin()">
+    <div class="admin-shell">
-        <!-- Sidebar -->
+        <aside class="admin-sidebar" aria-label="Primary">
-        <div class="w-64 bg-slate-900 p-6">
+            <div class="brand-block">
-            <div class="flex items-center gap-3 mb-8">
+                <div class="brand-badge" aria-hidden="true">LV</div>
-                <div class="w-8 h-8 bg-blue-600 rounded-full flex items-center justify-center text-white font-bold">LV</div>
+                <div class="brand-text">Admin</div>
-                <div class="text-xl font-bold">Admin</div>
             </div>
-            <nav class="space-y-2">
+
-                <a href="#" @click="currentTab = 'dashboard'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'dashboard' }">Dashboard</a>
+            <button id="logout-btn" type="button" class="btn btn-secondary btn-block">Sign out</button>
-                <a href="#" @click="currentTab = 'upload'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'upload' }">Upload Video</a>
+
-                <a href="#" @click="currentTab = 'playlist'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'playlist' }">Playlist</a>
+            <nav class="admin-nav" aria-label="Admin sections" role="tablist" aria-orientation="vertical">
-                <a href="#" @click="currentTab = 'schedule'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'schedule' }">Schedule</a>
+                <button type="button" id="tab-trigger-dashboard" role="tab" class="tab-trigger is-active" data-tab="dashboard" aria-controls="tab-dashboard" aria-selected="true">Dashboard</button>
-                <a href="#" @click="currentTab = 'moderation'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'moderation' }">Moderation</a>
+                <button type="button" id="tab-trigger-upload" role="tab" class="tab-trigger" data-tab="upload" aria-controls="tab-upload" aria-selected="false">Upload Video</button>
-                <a href="#" @click="currentTab = 'users'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'users' }">Users</a>
+                <button type="button" id="tab-trigger-playlist" role="tab" class="tab-trigger" data-tab="playlist" aria-controls="tab-playlist" aria-selected="false">Playlist</button>
-                <a href="#" @click="currentTab = 'analytics'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'analytics' }">Analytics</a>
+                <button type="button" id="tab-trigger-schedule" role="tab" class="tab-trigger" data-tab="schedule" aria-controls="tab-schedule" aria-selected="false">Schedule</button>
-                <a href="#" @click="currentTab = 'system'" class="block px-4 py-2 rounded-lg" :class="{ 'bg-blue-600': currentTab === 'system' }">System (Redis)</a>
+                <button type="button" id="tab-trigger-moderation" role="tab" class="tab-trigger" data-tab="moderation" aria-controls="tab-moderation" aria-selected="false">Moderation</button>
+                <button type="button" id="tab-trigger-chat-log" role="tab" class="tab-trigger" data-tab="chat-log" aria-controls="tab-chat-log" aria-selected="false">Chat Log</button>
+                <button type="button" id="tab-trigger-users" role="tab" class="tab-trigger" data-tab="users" aria-controls="tab-users" aria-selected="false">Users</button>
+                <button type="button" id="tab-trigger-analytics" role="tab" class="tab-trigger" data-tab="analytics" aria-controls="tab-analytics" aria-selected="false">Analytics</button>
+                <button type="button" id="tab-trigger-system" role="tab" class="tab-trigger" data-tab="system" aria-controls="tab-system" aria-selected="false">System</button>
             </nav>
-        </div>
+        </aside>
 
-        <!-- Main Content -->
+        <main class="admin-main" id="admin-main" tabindex="-1">
-        <div class="flex-1 p-8 overflow-auto">
+            <div id="tab-content-container" aria-live="polite">Loading...</div>
-            <template x-if="currentTab === 'dashboard'">
+        </main>
-                <div>
-                    <h1 class="text-3xl font-bold mb-8">Dashboard</h1>
-                    <div class="grid grid-cols-3 gap-6">
-                        <div class="bg-slate-800 p-6 rounded-3xl">
-                            <div class="text-emerald-400 text-sm">Concurrent Viewers</div>
-                            <div class="text-5xl font-bold mt-2" x-text="stats.viewers"></div>
-                        </div>
-                        <div class="bg-slate-800 p-6 rounded-3xl">
-                            <div class="text-blue-400 text-sm">Cache Hit Ratio</div>
-                            <div class="text-5xl font-bold mt-2" x-text="stats.cacheHit + '%'">95%</div>
-                        </div>
-                        <div class="bg-slate-800 p-6 rounded-3xl">
-                            <div class="text-amber-400 text-sm">R2 Usage</div>
-                            <div class="text-5xl font-bold mt-2" x-text="stats.r2Usage">12.4 GB</div>
-                        </div>
-                    </div>
-                </div>
-            </template>
-
-            <template x-if="currentTab === 'upload'">
-                <div>
-                    <h1 class="text-3xl font-bold mb-8">Upload Video</h1>
-                    <div class="border-2 border-dashed border-slate-600 rounded-3xl p-12 text-center">
-                        <input type="file" id="video-upload" class="hidden" accept="video/*" @change="uploadVideo">
-                        <button onclick="document.getElementById('video-upload').click()" class="bg-blue-600 hover:bg-blue-500 px-8 py-4 rounded-2xl text-lg font-medium">
-                            Drag & Drop or Click to Upload
-                        </button>
-                        <div id="upload-status" class="mt-6 text-sm"></div>
-                    </div>
-                </div>
-            </template>
-
-            <template x-if="currentTab === 'system'">
-                <div>
-                    <h1 class="text-3xl font-bold mb-8">System Configuration (Redis & Storage)</h1>
-                    <div class="bg-slate-800 p-8 rounded-3xl">
-                        <div class="grid grid-cols-2 gap-8">
-                            <div>
-                                <h3 class="font-medium mb-4">Redis Stats</h3>
-                                <div class="space-y-4">
-                                    <div class="flex justify-between">
-                                        <span>Memory Used</span>
-                                        <span class="font-mono">248 MB</span>
-                                    </div>
-                                    <div class="flex justify-between">
-                                        <span>Connected Clients</span>
-                                        <span class="font-mono">12</span>
-                                    </div>
-                                    <div class="flex justify-between">
-                                        <span>Rate Limit Threshold</span>
-                                        <input type="number" value="10" class="bg-slate-700 px-3 py-1 rounded w-20 text-center">
-                                    </div>
-                                </div>
-                            </div>
-                            <div>
-                                <h3 class="font-medium mb-4">Storage</h3>
-                                <div class="space-y-4">
-                                    <div class="flex justify-between">
-                                        <span>SQLite Size</span>
-                                        <span class="font-mono">142 MB</span>
-                                    </div>
-                                    <button onclick="runVacuum()" class="bg-slate-700 hover:bg-slate-600 px-6 py-2 rounded-xl">Run VACUUM</button>
-                                </div>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-            </template>
-        </div>
     </div>
 
-    <script>
+    <script type="module" src="/src/admin.ts"></script>
-        function admin() {
-            return {
-                currentTab: 'dashboard',
-                stats: {
-                    viewers: 142,
-                    cacheHit: 97,
-                    r2Usage: '18.4 GB'
-                },
-                init() {
-                    console.log('Admin Interface initialized (ADR-004/ADR-005)');
-                }
-            }
-        }
-
-        function uploadVideo(event) {
-            const file = event.target.files[0];
-            const status = document.getElementById('upload-status');
-            status.innerHTML = `Uploading ${file.name}... (normalization in progress)`;
-            setTimeout(() => {
-                status.innerHTML = `<span class="text-emerald-400">✓ ${file.name} normalized and uploaded to R2</span>`;
-            }, 1500);
-        }
-
-        function runVacuum() {
-            alert('VACUUM executed on SQLite database (per ADR-006). Audit log entry created.');
-        }
-    </script>
 </body>
 
 </html>

frontend/admin/login/index.html

@@ -0,0 +1,67 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Linear Void Admin Login</title>
+    <link rel="stylesheet" href="../../src/style.css" />
+</head>
+
+<body class="auth-body">
+    <main class="auth-shell" aria-label="Admin authentication">
+        <section class="auth-card" aria-labelledby="auth-title">
+            <p class="auth-kicker">Linear Void</p>
+            <h1 id="auth-title">Admin Login</h1>
+            <p class="auth-subtitle">Authenticate to access protected admin controls.</p>
+
+            <form id="login-form" class="form-stack" novalidate>
+                <label for="username">Username</label>
+                <input id="username" type="text" class="text-input" autocomplete="username" required />
+
+                <label for="password">Password</label>
+                <input id="password" type="password" class="text-input" autocomplete="current-password" required />
+
+                <button id="submit" type="submit" class="btn btn-primary btn-block">Sign in</button>
+                <p id="status" class="status-line" aria-live="polite"></p>
+            </form>
+        </section>
+    </main>
+
+    <script>
+        const form = document.getElementById('login-form');
+        const username = document.getElementById('username');
+        const password = document.getElementById('password');
+        const submit = document.getElementById('submit');
+        const status = document.getElementById('status');
+
+        form.addEventListener('submit', async (event) => {
+            event.preventDefault();
+            submit.disabled = true;
+            status.textContent = 'Signing in...';
+            status.className = 'status-line';
+
+            try {
+                const response = await fetch('/api/admin/login', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ username: username.value, password: password.value })
+                });
+
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+
+                window.location.href = '/admin/';
+            } catch (error) {
+                console.error('Failed to sign in', error);
+                status.textContent = 'Login failed. Check your credentials.';
+                status.className = 'status-line status-error';
+            } finally {
+                submit.disabled = false;
+            }
+        });
+    </script>
+</body>
+
+</html>

frontend/index.html

@@ -5,76 +5,59 @@
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>Linear Void - 24/7 Synchronized Channel</title>
-  <script src="https://cdn.tailwindcss.com"></script>
-  <script src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js" defer></script>
   <link rel="stylesheet" href="/src/style.css" />
 </head>
 
-<body class="bg-slate-950 text-slate-200">
+<body class="lv-body">
-  <div class="flex h-screen" x-data="app()">
+  <main class="viewer-shell" aria-label="Live player and chat">
-    <!-- Video Player -->
+    <header class="viewer-header">
-    <div class="flex-1 flex flex-col">
+      <div class="viewer-brand-group">
-      <div class="p-4 border-b border-slate-800 flex items-center justify-between bg-slate-900">
+        <div class="brand-badge" aria-hidden="true">LV</div>
-        <div class="flex items-center gap-3">
+        <div>
-          <div class="w-8 h-8 bg-blue-600 rounded-full flex items-center justify-center text-white font-bold">LV</div>
+          <h1 class="viewer-title">Linear Void</h1>
-          <div>
+          <p class="viewer-subtitle">24/7 Synchronized Channel • Live</p>
-            <h1 class="text-2xl font-bold text-white">Linear Void</h1>
+        </div>
-            <p class="text-xs text-emerald-400">24/7 Synchronized Channel • Live</p>
+      </div>
+      <button id="chat-toggle" type="button" class="btn btn-secondary chat-toggle-btn" onclick="toggleChatPanel()" aria-controls="chat-panel" aria-expanded="true">Hide Chat</button>
+    </header>
+
+    <section class="viewer-content" aria-label="Live stream and chat layout">
+      <section class="player-stage" aria-label="Video stage">
+        <video id="player" class="player" controls autoplay muted playsinline></video>
+        <div id="now-playing" class="now-playing-overlay" aria-live="polite">
+          <span id="np-title">Loading...</span>
+          <span id="np-next" class="np-next"></span>
+        </div>
+      </section>
+
+      <aside id="chat-panel" class="chat-sidebar" aria-label="Chat panel">
+        <header class="chat-header">
+          <div class="chat-room-title">
+            <span class="chat-live-marker" aria-hidden="true">●</span>
+            <span id="room-name">Main Channel</span>
           </div>
-        </div>
+          <button type="button" class="btn btn-secondary" onclick="togglePrivateDM()">New DM</button>
-        <div class="now-playing px-4 py-1 rounded-full text-sm font-medium flex items-center gap-2">
+        </header>
-          <div class="w-2 h-2 bg-emerald-400 rounded-full animate-pulse"></div>
-          <span id="now-playing">Loading schedule...</span>
-        </div>
-      </div>
 
-      <div class="flex-1 flex items-center justify-center p-8 bg-black relative">
+        <section id="messages" class="chat-messages" aria-live="polite" aria-label="Message stream"></section>
-        <video id="player" class="max-h-full rounded-xl shadow-2xl" controls autoplay></video>
+
-        <div id="now-playing-overlay" class="absolute bottom-8 left-8 bg-black/70 backdrop-blur-md px-6 py-3 rounded-2xl text-sm hidden">
+        <section id="presence-panel" class="presence-panel" aria-label="Online users">
-          <div class="flex items-center gap-3">
+          <div id="presence-list" class="presence-list"></div>
-            <div class="text-emerald-400">● LIVE</div>
+        </section>
-            <div id="overlay-title" class="font-medium"></div>
+
+        <div class="chat-input-area">
+          <div class="chat-input-row">
+            <label for="message-input" class="sr-only">Message input</label>
+            <input id="message-input" type="text" placeholder="Type a message..." class="input" onkeydown="if(event.key === 'Enter') sendMessage()" />
+            <button type="button" class="btn btn-primary" onclick="sendMessage()">Send</button>
           </div>
+          <p class="chat-note">
+            Synced with video • Moderation active
+          </p>
         </div>
-      </div>
+      </aside>
-
+    </section>
-      <div class="p-4 bg-slate-900 border-t border-slate-800 text-xs text-slate-400 flex justify-between">
+  </main>
-        <div>Latency: ~25s • Synced for all viewers (per ADR-001)</div>
-        <div class="flex gap-6">
-          <a href="#" onclick="switchRoom('main')" class="hover:text-white">Main Channel</a>
-          <a href="#" onclick="switchRoom('chill')" class="hover:text-white">Chill Room</a>
-          <a href="#" onclick="switchRoom('talk')" class="hover:text-white">Talk Room</a>
-        </div>
-      </div>
-    </div>
-
-    <!-- Chat Sidebar -->
-    <div class="w-96 flex flex-col border-l border-slate-800 bg-slate-900 chat-sidebar">
-      <div class="p-4 border-b border-slate-700 font-medium flex items-center justify-between">
-        <div class="flex items-center gap-2">
-          <span class="text-emerald-400">●</span>
-          <span id="room-name">Main Channel</span>
-        </div>
-        <button onclick="togglePrivateDM()" class="text-xs px-3 py-1 bg-slate-700 hover:bg-slate-600 rounded-lg">New DM</button>
-      </div>
-
-      <!-- Messages -->
-      <div id="messages" class="flex-1 p-4 overflow-y-auto space-y-4 text-sm">
-        <!-- Messages populated by JS -->
-      </div>
-
-      <!-- Input -->
-      <div class="p-4 border-t border-slate-700">
-        <div class="flex gap-2">
-          <input id="message-input" type="text" placeholder="Type a message..." class="input flex-1 px-4 py-3 rounded-2xl text-sm focus:outline-none" onkeydown="if(event.key === 'Enter') sendMessage()">
-          <button onclick="sendMessage()" class="bg-blue-600 hover:bg-blue-500 px-6 rounded-2xl text-sm font-medium">Send</button>
-        </div>
-        <div class="text-[10px] text-slate-500 mt-2 text-center">
-          Synced with video • Moderation active
-        </div>
-      </div>
-    </div>
-  </div>
 
   <script type="module" src="/src/main.ts"></script>
 </body>

frontend/package-lock.json

@@ -8,11 +8,7 @@
       "name": "frontend",
       "version": "0.0.0",
       "dependencies": {
-        "alpinejs": "^3.15.12",
+        "hls.js": "^1.6.16"
-        "autoprefixer": "^10.5.4",
-        "hls.js": "^1.6.16",
-        "postcss": "^8.5.25",
-        "tailwindcss": "^4.3.3"
       },
       "devDependencies": {
         "typescript": "~6.0.2",
@@ -375,131 +371,6 @@
         "tslib": "^2.4.0"
       }
     },
-    "node_modules/@vue/reactivity": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/@vue/reactivity/-/reactivity-3.1.5.tgz",
-      "integrity": "sha512-1tdfLmNjWG6t/CsPldh+foumYFo3cpyCHgBYQ34ylaMsJ+SNHQ1kApMIa8jN+i593zQuaw3AdWH0nJTARzCFhg==",
-      "license": "MIT",
-      "dependencies": {
-        "@vue/shared": "3.1.5"
-      }
-    },
-    "node_modules/@vue/shared": {
-      "version": "3.1.5",
-      "resolved": "https://registry.npmjs.org/@vue/shared/-/shared-3.1.5.tgz",
-      "integrity": "sha512-oJ4F3TnvpXaQwZJNF3ZK+kLPHKarDmJjJ6jyzVNDKH9md1dptjC7lWR//jrGuLdek/U6iltWxqAnYOu8gCiOvA==",
-      "license": "MIT"
-    },
-    "node_modules/alpinejs": {
-      "version": "3.15.12",
-      "resolved": "https://registry.npmjs.org/alpinejs/-/alpinejs-3.15.12.tgz",
-      "integrity": "sha512-nJvPAQVNPdZZ0NrExJ/kzQco3ijR8LwvCOadQecllESiqT4NyZ/57sN9V2XyvhlBGAbmlKYgeWZvYdKq99ij/Q==",
-      "license": "MIT",
-      "dependencies": {
-        "@vue/reactivity": "~3.1.1"
-      }
-    },
-    "node_modules/autoprefixer": {
-      "version": "10.5.4",
-      "resolved": "https://registry.npmjs.org/autoprefixer/-/autoprefixer-10.5.4.tgz",
-      "integrity": "sha512-MaU0U/za7N3r6brxD4YB/l4NSrFzLPlANv6wEuQVaIPlD3L4W9rFcQPbL/EilY9BHhHvhfcz3gInDLrEtWT4EA==",
-      "funding": [
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/postcss/"
-        },
-        {
-          "type": "tidelift",
-          "url": "https://tidelift.com/funding/github/npm/autoprefixer"
-        },
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/ai"
-        }
-      ],
-      "license": "MIT",
-      "dependencies": {
-        "browserslist": "^4.28.6",
-        "caniuse-lite": "^1.0.30001806",
-        "fraction.js": "^5.3.4",
-        "picocolors": "^1.1.1",
-        "postcss-value-parser": "^4.2.0"
-      },
-      "bin": {
-        "autoprefixer": "bin/autoprefixer"
-      },
-      "engines": {
-        "node": "^10 || ^12 || >=14"
-      },
-      "peerDependencies": {
-        "postcss": "^8.1.0"
-      }
-    },
-    "node_modules/baseline-browser-mapping": {
-      "version": "2.11.10",
-      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.10.tgz",
-      "integrity": "sha512-35JEvJ5/KKlbCHjMCsONI2w6HE88STjVdHk+C7d8LtcFxUjZR1KeLP9izofn2qs0KUxX5r4z73bwH/rd+JHacw==",
-      "license": "Apache-2.0",
-      "bin": {
-        "baseline-browser-mapping": "dist/cli.cjs"
-      },
-      "engines": {
-        "node": ">=6.0.0"
-      }
-    },
-    "node_modules/browserslist": {
-      "version": "4.28.7",
-      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.7.tgz",
-      "integrity": "sha512-JxV13hNrFxqjOc8alRbq9dK1MM79NEXYpma2B2J4wAtpWS5zIEIKqWPGCl7N4o7Uc7B7itylh7SuDujATRyyTw==",
-      "funding": [
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/browserslist"
-        },
-        {
-          "type": "tidelift",
-          "url": "https://tidelift.com/funding/github/npm/browserslist"
-        },
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/ai"
-        }
-      ],
-      "license": "MIT",
-      "dependencies": {
-        "baseline-browser-mapping": "^2.10.44",
-        "caniuse-lite": "^1.0.30001806",
-        "electron-to-chromium": "^1.5.393",
-        "node-releases": "^2.0.51",
-        "update-browserslist-db": "^1.2.3"
-      },
-      "bin": {
-        "browserslist": "cli.js"
-      },
-      "engines": {
-        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
-      }
-    },
-    "node_modules/caniuse-lite": {
-      "version": "1.0.30001806",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001806.tgz",
-      "integrity": "sha512-72Cuvd95zbSYPKq6Fhg8eDJRlzgWDf7/mtoZv6Qe/DYNCEBdNxoA3+rZAU2ZhGCpZlns3EssFavaZomckT5Uuw==",
-      "funding": [
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/browserslist"
-        },
-        {
-          "type": "tidelift",
-          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
-        },
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/ai"
-        }
-      ],
-      "license": "CC-BY-4.0"
-    },
     "node_modules/detect-libc": {
       "version": "2.1.2",
       "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
@@ -510,21 +381,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/electron-to-chromium": {
-      "version": "1.5.399",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.399.tgz",
-      "integrity": "sha512-lEcqhErbHjXRvd41rnWLpzbyU/IXfIYo7QwaFWmxGeLiLyY2TBCdHnWY88vB+p3ubnihRypDm66panXl7TylLA==",
-      "license": "ISC"
-    },
-    "node_modules/escalade": {
-      "version": "3.2.0",
-      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
-      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -543,19 +399,6 @@
         }
       }
     },
-    "node_modules/fraction.js": {
-      "version": "5.3.4",
-      "resolved": "https://registry.npmjs.org/fraction.js/-/fraction.js-5.3.4.tgz",
-      "integrity": "sha512-1X1NTtiJphryn/uLQz3whtY6jK3fTqoE3ohKs0tT+Ujr1W59oopxmoEh7Lu5p6vBaPbgoM0bzveAW4Qi5RyWDQ==",
-      "license": "MIT",
-      "engines": {
-        "node": "*"
-      },
-      "funding": {
-        "type": "github",
-        "url": "https://github.com/sponsors/rawify"
-      }
-    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -854,6 +697,7 @@
       "version": "3.3.16",
       "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.16.tgz",
       "integrity": "sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==",
+      "dev": true,
       "funding": [
         {
           "type": "github",
@@ -868,19 +712,11 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
-    "node_modules/node-releases": {
-      "version": "2.0.51",
-      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.51.tgz",
-      "integrity": "sha512-wRNIrw4DmVLKQlbgOMdkMx27Wrpzes2hh5Jtbi2bjPd+4wJstWIqP5A+lscnqbm0xxmT5Bpg8Lec5ItEBwx6BQ==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=18"
-      }
-    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
       "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "dev": true,
       "license": "ISC"
     },
     "node_modules/picomatch": {
@@ -900,6 +736,7 @@
       "version": "8.5.25",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.25.tgz",
       "integrity": "sha512-DTPx3RWSSnWyzLxQnlH0rJP+EW5ekl16ZU4/psbIhA0e53kJfdgaN5vKM+xP7yJtXVu+nfdVFmlgFDEKAe4Pyw==",
+      "dev": true,
       "funding": [
         {
           "type": "opencollective",
@@ -924,12 +761,6 @@
         "node": "^10 || ^12 || >=14"
       }
     },
-    "node_modules/postcss-value-parser": {
-      "version": "4.2.0",
-      "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz",
-      "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==",
-      "license": "MIT"
-    },
     "node_modules/rolldown": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.1.tgz",
@@ -968,17 +799,12 @@
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
       "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "dev": true,
       "license": "BSD-3-Clause",
       "engines": {
         "node": ">=0.10.0"
       }
     },
-    "node_modules/tailwindcss": {
-      "version": "4.3.3",
-      "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.3.tgz",
-      "integrity": "sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ==",
-      "license": "MIT"
-    },
     "node_modules/tinyglobby": {
       "version": "0.2.17",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
@@ -1018,36 +844,6 @@
         "node": ">=14.17"
       }
     },
-    "node_modules/update-browserslist-db": {
-      "version": "1.2.3",
-      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz",
-      "integrity": "sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==",
-      "funding": [
-        {
-          "type": "opencollective",
-          "url": "https://opencollective.com/browserslist"
-        },
-        {
-          "type": "tidelift",
-          "url": "https://tidelift.com/funding/github/npm/browserslist"
-        },
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/ai"
-        }
-      ],
-      "license": "MIT",
-      "dependencies": {
-        "escalade": "^3.2.0",
-        "picocolors": "^1.1.1"
-      },
-      "bin": {
-        "update-browserslist-db": "cli.js"
-      },
-      "peerDependencies": {
-        "browserslist": ">= 4.21.0"
-      }
-    },
     "node_modules/vite": {
       "version": "8.2.0",
       "resolved": "https://registry.npmjs.org/vite/-/vite-8.2.0.tgz",

frontend/package.json

@@ -1,22 +1,19 @@
 {
   "name": "frontend",
   "private": true,
-  "version": "0.0.0",
+  "version": "1.0.9",
   "type": "module",
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "lint": "tsc --noEmit"
   },
   "devDependencies": {
     "typescript": "~6.0.2",
     "vite": "^8.2.0"
   },
   "dependencies": {
-    "alpinejs": "^3.15.12",
+    "hls.js": "^1.6.16"
-    "autoprefixer": "^10.5.4",
-    "hls.js": "^1.6.16",
-    "postcss": "^8.5.25",
-    "tailwindcss": "^4.3.3"
   }
 }

frontend/public/admin/analytics.html

@@ -0,0 +1,53 @@
+<div class="panel-header-row">
+    <div>
+        <h1>Analytics</h1>
+        <p>Basic activity counters from chat history and moderation audit logs.</p>
+    </div>
+    <div class="button-row">
+        <select id="analytics-range" class="text-input" style="width:auto">
+            <option value="1h">Last hour</option>
+            <option value="6h">Last 6 hours</option>
+            <option value="24h" selected>Last 24 hours</option>
+            <option value="7d">Last 7 days</option>
+        </select>
+        <button id="reload-analytics-btn" type="button" class="btn btn-secondary">Reload analytics</button>
+    </div>
+</div>
+
+<div class="stat-grid">
+    <article class="stat-card">
+        <h2>Total Messages</h2>
+        <p id="analytics-total-messages" class="stat-value">0</p>
+    </article>
+    <article class="stat-card">
+        <h2>Last 24 Hours</h2>
+        <p id="analytics-messages-24h" class="stat-value">0</p>
+    </article>
+    <article class="stat-card">
+        <h2>Distinct Rooms</h2>
+        <p id="analytics-distinct-rooms" class="stat-value">0</p>
+    </article>
+    <article class="stat-card">
+        <h2>Moderation Actions</h2>
+        <p id="analytics-moderation-actions" class="stat-value">0</p>
+    </article>
+</div>
+
+<div class="panel-card">
+    <div class="panel-header-row">
+        <h2>Top Rooms</h2>
+        <p id="analytics-generated-at" class="small-muted">loading...</p>
+    </div>
+    <div class="table-wrap">
+        <table class="data-table">
+            <thead>
+                <tr>
+                    <th>Room</th>
+                    <th>Messages</th>
+                </tr>
+            </thead>
+            <tbody id="analytics-table-body"></tbody>
+        </table>
+    </div>
+    <p id="analytics-status" class="status-line" aria-live="polite">Loading analytics...</p>
+</div>

frontend/public/admin/chat-log.html

@@ -0,0 +1,46 @@
+<div class="panel-header-row">
+    <div>
+        <h1>Chat Log</h1>
+        <p>Browse and manage stored chat messages.</p>
+    </div>
+    <div class="button-row">
+        <button id="reload-chat-log-btn" type="button" class="btn btn-secondary">Reload</button>
+        <button id="bulk-delete-chat-log-btn" type="button" class="btn btn-danger" disabled>Delete Selected</button>
+    </div>
+</div>
+
+<div class="panel-card">
+    <div class="chat-log-filters">
+        <input id="chat-log-filter-room" class="text-input" type="text" placeholder="Room" />
+        <input id="chat-log-filter-username" class="text-input" type="text" placeholder="Username" />
+        <input id="chat-log-filter-text" class="text-input" type="text" placeholder="Message text" />
+        <button id="chat-log-filter-btn" type="button" class="btn btn-secondary">Filter</button>
+        <button id="chat-log-clear-filter-btn" type="button" class="btn btn-secondary">Clear</button>
+    </div>
+</div>
+
+<div class="panel-card">
+    <div class="table-wrap">
+        <table class="data-table">
+            <thead>
+                <tr>
+                    <th><input type="checkbox" id="chat-log-select-all" title="Select all" /></th>
+                    <th>ID</th>
+                    <th>Room</th>
+                    <th>Username</th>
+                    <th>Message</th>
+                    <th>Type</th>
+                    <th>Timestamp</th>
+                    <th>Actions</th>
+                </tr>
+            </thead>
+            <tbody id="chat-log-table-body"></tbody>
+        </table>
+    </div>
+    <div class="chat-log-pagination">
+        <button id="chat-log-prev-btn" type="button" class="btn btn-secondary" disabled>Previous</button>
+        <span id="chat-log-page-info" class="small-muted">Page 1</span>
+        <button id="chat-log-next-btn" type="button" class="btn btn-secondary" disabled>Next</button>
+    </div>
+    <p id="chat-log-status" class="status-line" aria-live="polite">Loading chat log...</p>
+</div>

frontend/public/admin/dashboard.html

@@ -0,0 +1,21 @@
+<h1>Dashboard</h1>
+<div class="stat-grid">
+    <article class="stat-card">
+        <h2>Concurrent Viewers</h2>
+        <p id="stat-viewers" class="stat-value">0</p>
+    </article>
+    <article class="stat-card">
+        <h2>Stored Messages</h2>
+        <p id="stat-stored-messages" class="stat-value">0</p>
+    </article>
+    <article class="stat-card">
+        <h2>Moderation Actions</h2>
+        <p id="stat-moderation-actions" class="stat-value">0</p>
+    </article>
+    <article class="stat-card">
+        <h2>Media Runtime</h2>
+        <p id="stat-media-runtime" class="stat-value">00:00:00</p>
+        <p id="stat-media-count" class="stat-caption">0 files</p>
+    </article>
+</div>
+<p id="overview-status" class="status-line" aria-live="polite">Loading live admin overview...</p>

frontend/public/admin/moderation.html

@@ -0,0 +1,61 @@
+<div class="panel-header-row">
+    <div>
+        <h1>Moderation</h1>
+        <p>Create moderation actions and review the recent immutable audit log.</p>
+    </div>
+    <div class="button-row">
+        <button id="reload-moderation-btn" type="button" class="btn btn-secondary">Reload logs</button>
+        <button id="export-chat-log-btn" type="button" class="btn btn-secondary">Export CSV</button>
+    </div>
+</div>
+
+<div class="moderation-grid">
+    <section class="panel-card">
+        <h2>New Action</h2>
+        <form id="moderation-form" class="form-stack">
+            <label>Action
+                <select id="mod-action" class="text-input">
+                    <option value="mute">mute</option>
+                    <option value="ban">ban</option>
+                    <option value="delete">delete</option>
+                    <option value="timeout">timeout</option>
+                </select>
+            </label>
+            <label>Target
+                <input id="mod-target" class="text-input" type="text" placeholder="username or message id" required />
+            </label>
+            <label>Moderator
+                <input id="mod-moderator" class="text-input" type="text" placeholder="admin" />
+            </label>
+            <label>Room
+                <input id="mod-room" class="text-input" type="text" placeholder="main" />
+            </label>
+            <label>Reason
+                <textarea id="mod-reason" class="text-input text-area" placeholder="Explain why this action is needed" required></textarea>
+            </label>
+            <button id="mod-submit" type="submit" class="btn btn-primary">Submit action</button>
+            <p id="moderation-status" class="status-line" aria-live="polite">Loading moderation logs...</p>
+        </form>
+    </section>
+
+    <section class="panel-card">
+        <div class="panel-header-row">
+            <h2>Recent Audit Log</h2>
+            <p class="small-muted">Latest entries</p>
+        </div>
+        <div class="table-wrap">
+            <table class="data-table">
+                <thead>
+                    <tr>
+                        <th>When</th>
+                        <th>Action</th>
+                        <th>Target</th>
+                        <th>Moderator</th>
+                        <th>Reason</th>
+                    </tr>
+                </thead>
+                <tbody id="moderation-table-body"></tbody>
+            </table>
+        </div>
+    </section>
+</div>

frontend/public/admin/playlist.html

@@ -0,0 +1,18 @@
+<div class="panel-header-row">
+    <div>
+        <h1>Playlist</h1>
+        <p>Edit the active concat playlist. Drag entries to reorder.</p>
+    </div>
+    <div class="button-row">
+        <button id="reload-playlist-btn" type="button" class="btn btn-secondary">Reload</button>
+        <button id="save-playlist-btn" type="button" class="btn btn-primary">Save playlist</button>
+    </div>
+</div>
+
+<div class="panel-card">
+    <div id="playlist-warnings" class="status-warnings" hidden></div>
+    <ul id="playlist-sortable" class="sortable-list" aria-label="Playlist entries"></ul>
+    <label for="playlist-content" class="sr-only">Playlist content (raw)</label>
+    <textarea id="playlist-content" class="text-input text-area" spellcheck="false" rows="6"></textarea>
+    <p id="playlist-status" class="status-line" aria-live="polite">Loading playlist...</p>
+</div>

frontend/public/admin/schedule.html

@@ -0,0 +1,53 @@
+<div class="panel-header-row">
+    <div>
+        <h1>Schedule</h1>
+        <p>Read-only view of the currently configured playout order.</p>
+    </div>
+    <button id="reload-schedule-btn" type="button" class="btn btn-secondary">Reload schedule</button>
+</div>
+
+<div class="panel-card">
+    <p class="small-muted"><span id="schedule-matched-entries">0</span>/<span id="schedule-total-entries">0</span> matched • total runtime <span id="schedule-total-runtime">00:00:00</span></p>
+    <div class="table-wrap">
+        <table class="data-table">
+            <thead>
+                <tr>
+                    <th>#</th>
+                    <th>Label</th>
+                    <th>Runtime</th>
+                    <th>Status</th>
+                    <th>Path</th>
+                </tr>
+            </thead>
+            <tbody id="schedule-table-body"></tbody>
+        </table>
+    </div>
+    <p id="schedule-status" class="status-line" aria-live="polite">Loading schedule...</p>
+</div>
+
+<div class="panel-card">
+    <h2>Schedule Overrides</h2>
+    <p>Insert scheduled overrides to play specific videos at specific times.</p>
+    <form id="override-form" class="form-stack" style="max-width:500px">
+        <label>Media ID <input id="override-media-id" type="number" class="text-input" required /></label>
+        <label>Start Time <input id="override-start" type="datetime-local" class="text-input" required /></label>
+        <label>End Time <input id="override-end" type="datetime-local" class="text-input" required /></label>
+        <label>Reason <input id="override-reason" type="text" class="text-input" placeholder="e.g. special event" /></label>
+        <button type="submit" class="btn btn-primary">Add Override</button>
+    </form>
+    <p id="override-status" class="status-line" aria-live="polite"></p>
+    <div class="table-wrap" style="margin-top:1rem">
+        <table class="data-table">
+            <thead>
+                <tr>
+                    <th>Media ID</th>
+                    <th>Start</th>
+                    <th>End</th>
+                    <th>Reason</th>
+                    <th></th>
+                </tr>
+            </thead>
+            <tbody id="override-table-body"></tbody>
+        </table>
+    </div>
+</div>

frontend/public/admin/system.html

@@ -0,0 +1,75 @@
+<h1>System Configuration</h1>
+<div class="panel-card split-grid">
+    <section>
+        <h2>Redis Stats</h2>
+        <dl class="kv-list">
+            <div>
+                <dt>Memory Used</dt>
+                <dd id="system-redis-memory">loading...</dd>
+            </div>
+            <div>
+                <dt>Connected Clients</dt>
+                <dd id="system-redis-clients">0</dd>
+            </div>
+            <div>
+                <dt>Redis Enabled</dt>
+                <dd id="system-redis-enabled">no</dd>
+            </div>
+        </dl>
+    </section>
+    <section>
+        <h2>Storage</h2>
+        <dl class="kv-list">
+            <div>
+                <dt>Database Driver</dt>
+                <dd id="system-db-driver">loading...</dd>
+            </div>
+            <div>
+                <dt>Stored Messages</dt>
+                <dd id="system-stored-messages">0</dd>
+            </div>
+            <div>
+                <dt>Last Refresh</dt>
+                <dd id="system-generated-at">loading...</dd>
+            </div>
+            <div>
+                <dt>Playlist Path</dt>
+                <dd id="system-playlist-path">loading...</dd>
+            </div>
+            <div>
+                <dt>Playlist Present</dt>
+                <dd id="system-playlist-present">no</dd>
+            </div>
+        </dl>
+    </section>
+</div>
+
+<div class="panel-card">
+    <div class="panel-header-row">
+        <h2>Service Health</h2>
+        <button id="reload-system-btn" type="button" class="btn btn-secondary">Reload health</button>
+    </div>
+    <div id="system-services" class="service-list"></div>
+    <p id="system-status" class="status-line" aria-live="polite">Loading system summary...</p>
+</div>
+
+<div class="panel-card">
+    <h2>Runtime Configuration</h2>
+    <form id="config-form" class="form-stack" style="max-width:400px">
+        <label>Rate Limit Max <input id="config-rate-max" type="number" class="text-input" /></label>
+        <label>Rate Limit Window (seconds) <input id="config-rate-window" type="number" class="text-input" /></label>
+        <button type="submit" class="btn btn-primary">Save Config</button>
+    </form>
+    <p id="config-status" class="status-line" aria-live="polite"></p>
+</div>
+
+<div class="panel-card">
+    <h2>Service Control</h2>
+    <p class="small-muted">Restart individual services (manual — container restart commands returned by API).</p>
+    <div class="button-row">
+        <button class="btn btn-secondary restart-btn" data-service="playout">Restart Playout</button>
+        <button class="btn btn-secondary restart-btn" data-service="chat">Restart Chat</button>
+        <button class="btn btn-secondary restart-btn" data-service="nginx">Restart Nginx</button>
+    </div>
+    <p id="restart-status" class="status-line" aria-live="polite"></p>
+</div>

frontend/public/admin/upload.html

@@ -0,0 +1,41 @@
+<div class="panel-header-row">
+    <div>
+        <h1>Upload Video</h1>
+        <p>Upload media files into the local media library mounted for playout.</p>
+    </div>
+    <button id="reload-media-btn" type="button" class="btn btn-secondary">Reload library</button>
+</div>
+
+<div id="upload-dropzone" class="upload-dropzone">
+    <input type="file" id="video-upload" accept="video/*,.mp4,.mov,.mkv,.webm" hidden />
+    <button id="upload-trigger-btn" type="button" class="btn btn-primary btn-large">Drag and Drop or Click to Upload</button>
+    <p class="small-muted">Resumable chunk upload enabled • up to 2GB per file.</p>
+    <div id="media-upload-progress-wrap" class="upload-progress" hidden>
+        <progress id="media-upload-progress" value="0" max="100"></progress>
+        <p id="media-upload-progress-text" class="small-muted">Uploading (0%)</p>
+    </div>
+    <p id="media-status" class="status-line" aria-live="polite">Loading media library...</p>
+</div>
+
+<div class="panel-card">
+    <div class="panel-header-row">
+        <h2>Media Library</h2>
+        <p id="media-generated-at" class="small-muted">loading...</p>
+    </div>
+    <div class="table-wrap">
+        <table class="data-table">
+            <thead>
+                <tr>
+                    <th>File</th>
+                    <th>Title</th>
+                    <th>Runtime</th>
+                    <th>Status</th>
+                    <th>Size</th>
+                    <th>Modified</th>
+                    <th>Actions</th>
+                </tr>
+            </thead>
+            <tbody id="media-table-body"></tbody>
+        </table>
+    </div>
+</div>

frontend/public/admin/users.html

@@ -0,0 +1,24 @@
+<div class="panel-header-row">
+    <div>
+        <h1>Users</h1>
+        <p>Current room presence derived from Redis presence keys.</p>
+    </div>
+    <button id="reload-users-btn" type="button" class="btn btn-secondary">Reload users</button>
+</div>
+
+<div class="panel-card">
+    <div class="table-wrap">
+        <table class="data-table">
+            <thead>
+                <tr>
+                    <th>Username</th>
+                    <th>Room</th>
+                    <th>Online</th>
+                    <th>Actions</th>
+                </tr>
+            </thead>
+            <tbody id="users-table-body"></tbody>
+        </table>
+    </div>
+    <p id="users-status" class="status-line" aria-live="polite">Loading active users...</p>
+</div>

frontend/src/main.ts

@@ -1,28 +1,71 @@
-import Hls from "hls.js";
 import "./style.css";
 
-// Main application state with Alpine.js
+type HlsClass = (typeof import("hls.js"))["default"];
+
 declare global {
   interface Window {
-    app: () => any;
     switchRoom: (room: string) => void;
     sendMessage: () => void;
     togglePrivateDM: () => void;
+    toggleChatPanel: () => void;
   }
 }
 
-let hls: Hls | null = null;
+let hls: InstanceType<HlsClass> | null = null;
 let ws: WebSocket | null = null;
 let currentRoom = "main";
 let username = "viewer" + Math.floor(Math.random() * 1000);
+let chatVisible = true;
+const onlineUsers = new Set<string>();
+
+function resolveWebSocketBaseUrl() {
+  const configuredUrl = import.meta.env.VITE_PUBLIC_WS_URL?.trim();
+
+  if (configuredUrl) {
+    return configuredUrl;
+  }
+
+  const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+  return `${protocol}//${window.location.host}/ws`;
+}
+
+function resolveManifestUrl() {
+  const configuredUrl = import.meta.env.VITE_PUBLIC_HLS_URL?.trim();
+  const cacheBust = `stream=${Date.now()}`;
+  const sameOriginManifestUrl = new URL(
+    "/hls/playlist.m3u8",
+    window.location.origin,
+  );
+  sameOriginManifestUrl.searchParams.set("stream", cacheBust);
+
+  const allowCrossOriginManifest =
+    import.meta.env.VITE_PUBLIC_HLS_CROSS_ORIGIN?.trim().toLowerCase() ===
+    "true";
+
+  if (configuredUrl) {
+    const manifestUrl = new URL(configuredUrl);
+    manifestUrl.searchParams.set("stream", cacheBust);
+
+    if (
+      !allowCrossOriginManifest &&
+      manifestUrl.origin !== window.location.origin
+    ) {
+      return sameOriginManifestUrl.toString();
+    }
+
+    return manifestUrl.toString();
+  }
+
+  return sameOriginManifestUrl.toString();
+}
 
 function connectWebSocket(room: string) {
   if (ws) ws.close();
 
-  const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+  const socketUrl = new URL(resolveWebSocketBaseUrl());
-  ws = new WebSocket(
+  socketUrl.searchParams.set("username", username);
-    `${protocol}//localhost:3000/ws?username=${username}&room=${room}`,
+  socketUrl.searchParams.set("room", room);
-  );
+  ws = new WebSocket(socketUrl);
 
   ws.onopen = () => {
     console.log(`Connected to chat room: ${room}`);
@@ -32,6 +75,19 @@ function connectWebSocket(room: string) {
   ws.onmessage = (event) => {
     const msg = JSON.parse(event.data);
     addMessage(msg.type || "public", msg.text, msg.username, msg.timestamp);
+
+    // Track presence from system join/leave messages
+    if (msg.type === "system" && msg.username === "system") {
+      const joined = msg.text?.match(/^(\S+) joined /);
+      const left = msg.text?.match(/^(\S+) left /);
+      if (joined) {
+        onlineUsers.add(joined[1]);
+        renderPresence();
+      } else if (left) {
+        onlineUsers.delete(left[1]);
+        renderPresence();
+      }
+    }
   };
 
   ws.onclose = () => {
@@ -48,17 +104,21 @@ function addMessage(
 ) {
   const messages = document.getElementById("messages")!;
   const div = document.createElement("div");
-  div.className = `message flex ${type === "system" ? "justify-center" : sender === username ? "justify-end" : "justify-start"}`;
+  div.className = "message-row";
 
   if (type === "system") {
-    div.innerHTML = `<div class="text-xs text-slate-400 bg-slate-800 px-3 py-1 rounded-full">${text}</div>`;
+    div.classList.add("message-system-row");
+    div.innerHTML = `<div class="message-system">${text}</div>`;
   } else {
+    div.classList.add(
+      sender === username ? "message-self-row" : "message-other-row",
+    );
     div.innerHTML = `
-      <div class="${sender === username ? "bg-blue-600" : "bg-slate-700"} px-4 py-2 rounded-3xl max-w-[75%]">
+      <article class="message-bubble ${sender === username ? "message-self" : "message-other"}">
-        ${sender && sender !== username ? `<div class="text-xs text-blue-300">${sender}</div>` : ""}
+        ${sender && sender !== username ? `<div class="message-sender">${sender}</div>` : ""}
-        <div>${text}</div>
+        <div class="message-text">${text}</div>
-        <div class="text-[10px] text-slate-400 mt-1">${new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</div>
+        <time class="message-time">${new Date(timestamp).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" })}</time>
-      </div>
+      </article>
     `;
   }
 
@@ -66,6 +126,81 @@ function addMessage(
   messages.scrollTop = messages.scrollHeight;
 }
 
+function renderPresence() {
+  const list = document.getElementById("presence-list");
+  if (!list) return;
+  const sorted = [...onlineUsers].sort();
+  list.innerHTML = sorted
+    .map(
+      (u) =>
+        `<span class="presence-dot" title="${u}"><span class="presence-indicator"></span>${u}</span>`,
+    )
+    .join("");
+}
+
+async function refreshSchedule() {
+  try {
+    const res = await fetch("/api/schedule");
+    if (!res.ok) return;
+    const data = await res.json();
+    const entries = data.entries as Array<{ title: string; status: string }>;
+    if (entries.length > 0) {
+      const np = document.getElementById("np-title");
+      const nn = document.getElementById("np-next");
+      if (np) np.textContent = `Now: ${entries[0].title}`;
+      if (nn && entries.length > 1) {
+        nn.textContent = `Up next: ${entries[1].title}`;
+      }
+    }
+  } catch {
+    // Schedule unavailable — non-critical
+  }
+}
+
+async function initPlayerAndChat() {
+  const video = document.getElementById("player") as HTMLVideoElement;
+  const manifestUrl = resolveManifestUrl();
+
+  if (video.canPlayType("application/vnd.apple.mpegurl")) {
+    video.src = manifestUrl;
+    video.addEventListener("loadedmetadata", () => video.play());
+  } else {
+    try {
+      const { default: Hls } = await import("hls.js");
+      if (Hls.isSupported()) {
+        hls = new Hls();
+        hls.loadSource(manifestUrl);
+        hls.attachMedia(video);
+        hls.on(Hls.Events.MANIFEST_PARSED, () => video.play());
+      }
+    } catch (error) {
+      console.error("Failed to load HLS player", error);
+      addMessage("system", "Unable to initialize video player.");
+    }
+  }
+
+  connectWebSocket("main");
+
+  // Start schedule polling
+  refreshSchedule();
+  setInterval(refreshSchedule, 30000);
+
+  console.log(
+    "Linear Void Frontend initialized - HLS Player + Chat Sidebar ready",
+  );
+}
+
+function toggleChatPanel() {
+  const shell = document.querySelector(".viewer-shell");
+  const toggle = document.getElementById("chat-toggle");
+  if (!shell || !toggle) return;
+
+  chatVisible = !chatVisible;
+  shell.classList.toggle("chat-collapsed", !chatVisible);
+  toggle.textContent = chatVisible ? "Hide Chat" : "Show Chat";
+  toggle.setAttribute("aria-expanded", String(chatVisible));
+}
+
 function sendMessage() {
   const input = document.getElementById("message-input") as HTMLInputElement;
   const text = input.value.trim();
@@ -100,64 +235,11 @@ function togglePrivateDM() {
   }
 }
 
-// Alpine.js app
-window.app = () => {
-  return {
-    init() {
-      // Initialize Tailwind
-      // @ts-ignore
-      tailwind.config = {
-        content: [],
-        theme: { extend: {} },
-      };
-
-      // Initialize HLS Player
-      const video = document.getElementById("player") as HTMLVideoElement;
-      const manifestUrl = "http://localhost:8080/hls/playlist.m3u8"; // from nginx/pla yout
-
-      if (Hls.isSupported()) {
-        hls = new Hls();
-        hls.loadSource(manifestUrl);
-        hls.attachMedia(video);
-        hls.on(Hls.Events.MANIFEST_PARSED, () => video.play());
-      } else if (video.canPlayType("application/vnd.apple.mpegurl")) {
-        video.src = manifestUrl;
-        video.addEventListener("loadedmetadata", () => video.play());
-      }
-
-      // Connect to default chat room
-      connectWebSocket("main");
-
-      // Simulate now playing
-      setInterval(() => {
-        const titles = [
-          "Midnight Jazz Lounge",
-          "Synthwave Nights",
-          "Classic Cinema",
-          "Ambient Void",
-        ];
-        document.getElementById("now-playing")!.textContent =
-          titles[Math.floor(Math.random() * titles.length)];
-        const overlay = document.getElementById("now-playing-overlay")!;
-        overlay.classList.remove("hidden");
-        document.getElementById("overlay-title")!.textContent =
-          titles[Math.floor(Math.random() * titles.length)];
-      }, 15000);
-
-      console.log(
-        "Linear Void Frontend initialized - HLS Player + Chat Sidebar ready",
-      );
-    },
-  };
-};
-
-// Make functions global for onclick handlers
 window.switchRoom = switchRoom;
 window.sendMessage = sendMessage;
 window.togglePrivateDM = togglePrivateDM;
+window.toggleChatPanel = toggleChatPanel;
 
-// Auto initialize when loaded
 document.addEventListener("DOMContentLoaded", () => {
-  // @ts-ignore
+  void initPlayerAndChat();
-  window.app().init();
 });

frontend/tailwind.config.js

@@ -1,8 +0,0 @@
-/** @type {import('tailwindcss').Config} */
-export default {
-  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-};

frontend/vite.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  envDir: "..",
+  build: {
+    chunkSizeWarningLimit: 600,
+    rollupOptions: {
+      input: {
+        main: "index.html",
+        admin: "admin/index.html",
+        adminLogin: "admin/login/index.html",
+      },
+    },
+  },
+});

infrastructure/nginx/Dockerfile

@@ -1,9 +1,21 @@
+# Stage 1: Build frontend
+FROM node:20-alpine AS builder
+WORKDIR /build
+COPY frontend/package*.json ./
+RUN npm ci
+COPY frontend/ .
+RUN npm run build
+
+# Stage 2: Nginx with bundled frontend
 FROM nginx:alpine
 
-COPY nginx.conf /etc/nginx/nginx.conf
+COPY infrastructure/nginx/nginx.conf /etc/nginx/nginx.conf
 
-# Create directories for HLS and frontend
+# Copy prebuilt frontend from builder stage
-RUN mkdir -p /usr/share/nginx/html/hls /usr/share/nginx/html/admin
+COPY --from=builder /build/dist/ /srv/frontend/
+
+# Create HLS directory
+RUN mkdir -p /srv/hls
 
 EXPOSE 80
 CMD ["nginx", "-g", "daemon off;"]

infrastructure/nginx/nginx.conf

@@ -3,13 +3,69 @@ events {
 }
 
 http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    resolver 127.0.0.11 ipv6=off valid=30s;
+
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        '' close;
+    }
+
     server {
         listen 80;
-        server_name localhost;
+        server_name www.linearvoid.tv;
 
-        root /usr/share/nginx/html;
+        return 301 https://linearvoid.tv$request_uri;
+    }
+
+    server {
+        listen 80 default_server;
+        server_name linearvoid.tv localhost 127.0.0.1;
+
+        # Resumable admin upload chunks are 8MB by default; allow safe headroom.
+        client_max_body_size 64m;
+
+        root /srv/frontend;
         index index.html;
 
+        location = /admin {
+            return 301 /admin/;
+        }
+
+        location = /admin/login {
+            return 301 /admin/login/;
+        }
+
+        location = /_admin_auth {
+            internal;
+            set $chat_upstream http://chat:3000;
+            proxy_pass $chat_upstream/api/admin/session;
+            proxy_http_version 1.1;
+            proxy_pass_request_body off;
+            proxy_set_header Content-Length "";
+            proxy_set_header Cookie $http_cookie;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        }
+
+        location /admin/login/ {
+            try_files $uri $uri/ /admin/login/index.html;
+        }
+
+        location /admin/ {
+            auth_request /_admin_auth;
+            error_page 401 = @admin_login_redirect;
+            try_files $uri $uri/ /admin/index.html;
+        }
+
+        location /assets/ {
+            try_files $uri =404;
+        }
+
         # Serve static frontend
         location / {
             try_files $uri $uri/ /index.html;
@@ -17,24 +73,153 @@ http {
 
         # Proxy chat WebSocket
         location /ws {
-            proxy_pass http://chat:3000;
+            set $chat_upstream http://chat:3000;
+            proxy_pass $chat_upstream;
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
-            proxy_set_header Connection "upgrade";
+            proxy_set_header Connection $connection_upgrade;
             proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
         }
 
-        # Serve HLS from playout (with cache headers for Cloudflare)
+        location = /api/admin/login {
-        location /hls/ {
+            set $chat_upstream http://chat:3000;
-            alias /usr/share/nginx/html/hls/;
+            proxy_pass $chat_upstream;
-            add_header Cache-Control "public, max-age=3600";
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Cookie $http_cookie;
+        }
+
+        location = /api/admin/logout {
+            set $chat_upstream http://chat:3000;
+            proxy_pass $chat_upstream;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Cookie $http_cookie;
+        }
+
+        location = /api/admin/session {
+            set $chat_upstream http://chat:3000;
+            proxy_pass $chat_upstream;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Cookie $http_cookie;
+        }
+
+        location /api/admin/ {
+            auth_request /_admin_auth;
+            error_page 401 = @admin_api_unauthorized;
+            set $chat_upstream http://chat:3000;
+            proxy_pass $chat_upstream;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header Cookie $http_cookie;
+        }
+
+        location /api/ {
+            set $chat_upstream http://chat:3000;
+            proxy_pass $chat_upstream;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        }
+
+        location = /metrics {
+            set $chat_upstream http://chat:3000;
+            proxy_pass $chat_upstream;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Forwarded-Host $host;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        }
+
+        location @admin_api_unauthorized {
+            add_header Content-Type application/json;
+            return 401 '{"error":"unauthorized"}';
+        }
+
+        location @admin_login_redirect {
+            return 302 /admin/login/;
+        }
+
+        location = /hls/playlist.m3u8 {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin "*";
+                add_header Access-Control-Allow-Methods "GET, OPTIONS";
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
+            alias /srv/hls/playlist.m3u8;
+            add_header Cache-Control "no-store, no-cache, must-revalidate, max-age=0";
             add_header Access-Control-Allow-Origin "*";
         }
 
-        # Health checks
+        location = /hls/init.mp4 {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin "*";
+                add_header Access-Control-Allow-Methods "GET, OPTIONS";
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
+            alias /srv/hls/init.mp4;
+            add_header Cache-Control "public, max-age=31536000, immutable";
+            add_header Access-Control-Allow-Origin "*";
+        }
+
+        location ~* ^/hls/(.+\.(ts|m4s))$ {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin "*";
+                add_header Access-Control-Allow-Methods "GET, OPTIONS";
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
+            alias /srv/hls/$1;
+            add_header Cache-Control "public, max-age=31536000, immutable";
+            add_header Access-Control-Allow-Origin "*";
+        }
+
+        # Local/dev fallback HLS origin. Production media should use MEDIA_DOMAIN.
+        location /hls/ {
+            if ($request_method = OPTIONS) {
+                add_header Access-Control-Allow-Origin "*";
+                add_header Access-Control-Allow-Methods "GET, OPTIONS";
+                add_header Access-Control-Max-Age 86400;
+                return 204;
+            }
+            alias /srv/hls/;
+            add_header Cache-Control "public, max-age=60";
+            add_header Access-Control-Allow-Origin "*";
+        }
+
+        # Health checks — aggregated from upstream services
         location /health {
-            return 200 "healthy";
+            default_type application/json;
-            add_header Content-Type text/plain;
+            return 200 '{"status":"ok","service":"nginx","timestamp":"$time_iso8601"}';
+        }
+
+        location /nginx-status {
+            stub_status on;
+            allow 127.0.0.1;
+            allow 172.16.0.0/12;
+            allow 192.168.0.0/16;
+            deny all;
         }
     }
 }

monitoring/grafana/dashboard.json

@@ -0,0 +1,39 @@
+{
+  "title": "Linear Void Monitoring",
+  "panels": [
+    {
+      "title": "Concurrent Viewers",
+      "type": "timeseries",
+      "targets": [{ "expr": "linearvoid_chat_connected_clients" }]
+    },
+    {
+      "title": "Stored Messages",
+      "type": "stat",
+      "targets": [
+        {
+          "expr": "linearvoid_chat_messages_total"
+        }
+      ]
+    },
+    {
+      "title": "Moderation Actions",
+      "type": "timeseries",
+      "targets": [{ "expr": "linearvoid_chat_moderation_actions_total" }]
+    },
+    {
+      "title": "Redis Reachable",
+      "type": "stat",
+      "targets": [{ "expr": "linearvoid_chat_redis_up" }]
+    },
+    {
+      "title": "Admin Sessions",
+      "type": "timeseries",
+      "targets": [{ "expr": "linearvoid_chat_admin_sessions_active" }]
+    },
+    {
+      "title": "Chat Scrape Health",
+      "type": "stat",
+      "targets": [{ "expr": "up{job=\"chat\"}" }]
+    }
+  ]
+}

monitoring/grafana/dashboards/dashboard.yml

@@ -0,0 +1,12 @@
+apiVersion: 1
+
+providers:
+  - name: "default"
+    orgId: 1
+    folder: ""
+    type: file
+    disableDeletion: false
+    updateIntervalSeconds: 10
+    allowUiUpdates: true
+    options:
+      path: /etc/grafana/provisioning/dashboards

monitoring/grafana/datasources/datasource.yml

@@ -0,0 +1,9 @@
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    type: prometheus
+    access: proxy
+    url: http://prometheus:9090
+    isDefault: true
+    editable: true

monitoring/prometheus/alerts.yml

@@ -0,0 +1,74 @@
+groups:
+  - name: linearvoid
+    rules:
+      - alert: ChatDown
+        expr: up{job="chat"} == 0
+        for: 2m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Chat service is down"
+          description: "Chat service has been unreachable for 2 minutes."
+
+      - alert: PlayoutDown
+        expr: up{job="playout"} == 0
+        for: 2m
+        labels:
+          severity: critical
+        annotations:
+          summary: "Playout service is down"
+          description: "Playout service has been unreachable for 2 minutes."
+
+      - alert: RedisDown
+        expr: linearvoid_chat_redis_up == 0
+        for: 2m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Redis is unreachable"
+          description: "Chat service cannot reach Redis. Rate limiting and presence tracking degraded."
+
+      - alert: PlayoutSlateActive
+        expr: linearvoid_playout_mode == 1
+        for: 1m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Playout in slate fallback mode"
+          description: "Playout has switched to emergency slate. Check playout logs."
+
+      - alert: HighChatLatency
+        expr: rate(linearvoid_chat_messages_total[5m]) < 0.01
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Unusually low chat message rate"
+          description: "Message rate below 0.01/s for 5 minutes. Check chat service health."
+
+      - alert: PrometheusWALFailing
+        expr: increase(prometheus_tsdb_wal_writes_failed_total[5m]) > 0
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Prometheus WAL writes failing"
+          description: "Prometheus TSDB WAL write failures detected."
+
+      - alert: HighCPU
+        expr: 100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80
+        for: 10m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High CPU usage"
+          description: "CPU usage above 80% for 10 minutes on {{ $labels.instance }}."
+
+      - alert: LowDiskSpace
+        expr: (node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"}) * 100 < 10
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "Low disk space"
+          description: "Less than 10% disk space available on {{ $labels.instance }}."

monitoring/prometheus/prometheus.yml

@@ -0,0 +1,28 @@
+global:
+  scrape_interval: 15s
+
+rule_files:
+  - "/etc/prometheus/alerts.yml"
+
+scrape_configs:
+  - job_name: "chat"
+    static_configs:
+      - targets: ["chat:3000"]
+  - job_name: "playout"
+    static_configs:
+      - targets: ["playout:8081"]
+  - job_name: "nginx"
+    static_configs:
+      - targets: ["nginx-exporter:9113"]
+  - job_name: "redis"
+    static_configs:
+      - targets: ["redis-exporter:9121"]
+  - job_name: "postgres"
+    static_configs:
+      - targets: ["postgres-exporter:9187"]
+  - job_name: "node"
+    static_configs:
+      - targets: ["node-exporter:9100"]
+  - job_name: "prometheus"
+    static_configs:
+      - targets: ["prometheus:9090"]

scripts/backup-db.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Daily PostgreSQL backup to R2 (14-day retention)
+# Schedule: cron daily. Requires: pg_dump, aws CLI or rclone for R2.
+set -e
+
+BACKUP_DIR="${BACKUP_DIR:-/tmp/linearvoid-backups}"
+RETENTION_DAYS="${RETENTION_DAYS:-14}"
+R2_BUCKET="${R2_BUCKET:-linearvoid-backups}"
+DB_URL="${DATABASE_URL:-postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable}"
+
+TIMESTAMP=$(date +%Y%m%d)
+BACKUP_FILE="$BACKUP_DIR/daily/db_${TIMESTAMP}.dump"
+
+mkdir -p "$(dirname "$BACKUP_FILE")"
+
+echo "[$(date -Iseconds)] Starting daily backup..."
+
+# Extract connection details from DATABASE_URL
+DB_HOST=$(echo "$DB_URL" | sed -n 's/.*@\([^:]*\).*/\1/p')
+DB_PORT=$(echo "$DB_URL" | sed -n 's/.*:\([0-9]*\)\/.*/\1/p')
+DB_USER=$(echo "$DB_URL" | sed -n 's/.*:\/\/\([^:]*\).*/\1/p')
+DB_NAME=$(echo "$DB_URL" | sed -n 's/.*\/\([^?]*\).*/\1/p')
+DB_PASS=$(echo "$DB_URL" | sed -n 's/.*:\/\/[^:]*:\([^@]*\).*/\1/p')
+
+export PGPASSWORD="${DB_PASS}"
+
+# Dump
+pg_dump -h "${DB_HOST:-db}" -p "${DB_PORT:-5432}" -U "${DB_USER:-linearvoid}" \
+        -Fc -f "$BACKUP_FILE" "${DB_NAME:-linearvoid}"
+
+echo "  Backup: $BACKUP_FILE ($(du -h "$BACKUP_FILE" | cut -f1))"
+
+# Upload to R2
+if [ -n "$R2_ENDPOINT" ] && [ -n "$R2_ACCESS_KEY_ID" ]; then
+    aws s3 cp "$BACKUP_FILE" "s3://${R2_BUCKET}/daily/db_${TIMESTAMP}.dump" \
+        --endpoint-url "$R2_ENDPOINT" --no-verify-ssl 2>/dev/null && \
+        echo "  Uploaded to R2: daily/db_${TIMESTAMP}.dump" || \
+        echo "  WARNING: R2 upload failed"
+fi
+
+# Cleanup old backups
+find "$BACKUP_DIR/daily" -name "db_*.dump" -mtime "+${RETENTION_DAYS}" -delete 2>/dev/null || true
+echo "  Cleaned up backups older than ${RETENTION_DAYS} days"
+
+echo "[$(date -Iseconds)] Daily backup complete."

scripts/backup-weekly.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Weekly full PostgreSQL backup to R2 (8-week retention)
+# Schedule: cron weekly (runs backup-db.sh with weekly prefix)
+set -e
+
+BACKUP_DIR="${BACKUP_DIR:-/tmp/linearvoid-backups}"
+RETENTION_WEEKS="${RETENTION_WEEKS:-8}"
+R2_BUCKET="${R2_BUCKET:-linearvoid-backups}"
+DB_URL="${DATABASE_URL:-postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable}"
+
+TIMESTAMP=$(date +%Y%m%d)
+BACKUP_FILE="$BACKUP_DIR/weekly/db_${TIMESTAMP}.dump"
+
+mkdir -p "$(dirname "$BACKUP_FILE")"
+
+echo "[$(date -Iseconds)] Starting weekly full backup..."
+
+DB_HOST=$(echo "$DB_URL" | sed -n 's/.*@\([^:]*\).*/\1/p')
+DB_PORT=$(echo "$DB_URL" | sed -n 's/.*:\([0-9]*\)\/.*/\1/p')
+DB_USER=$(echo "$DB_URL" | sed -n 's/.*:\/\/\([^:]*\).*/\1/p')
+DB_NAME=$(echo "$DB_URL" | sed -n 's/.*\/\([^?]*\).*/\1/p')
+DB_PASS=$(echo "$DB_URL" | sed -n 's/.*:\/\/[^:]*:\([^@]*\).*/\1/p')
+
+export PGPASSWORD="${DB_PASS}"
+
+pg_dump -h "${DB_HOST:-db}" -p "${DB_PORT:-5432}" -U "${DB_USER:-linearvoid}" \
+        -Fc -f "$BACKUP_FILE" "${DB_NAME:-linearvoid}"
+
+echo "  Backup: $BACKUP_FILE ($(du -h "$BACKUP_FILE" | cut -f1))"
+
+# Verify integrity
+pg_restore --list "$BACKUP_FILE" > /dev/null 2>&1 && \
+    echo "  Integrity check: PASSED" || \
+    echo "  WARNING: Integrity check FAILED"
+
+# Upload
+if [ -n "$R2_ENDPOINT" ] && [ -n "$R2_ACCESS_KEY_ID" ]; then
+    aws s3 cp "$BACKUP_FILE" "s3://${R2_BUCKET}/weekly/db_${TIMESTAMP}.dump" \
+        --endpoint-url "$R2_ENDPOINT" --no-verify-ssl 2>/dev/null && \
+        echo "  Uploaded to R2: weekly/db_${TIMESTAMP}.dump" || \
+        echo "  WARNING: R2 upload failed"
+fi
+
+# Cleanup
+find "$BACKUP_DIR/weekly" -name "db_*.dump" -mtime "+$((RETENTION_WEEKS * 7))" -delete 2>/dev/null || true
+echo "  Cleaned up backups older than ${RETENTION_WEEKS} weeks"
+
+echo "[$(date -Iseconds)] Weekly backup complete."

scripts/generate-slate.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Generate emergency slate video + pre-rendered HLS segments for failover.
+# Output: data/slate/ (slate MP4 + HLS segments + manifest)
+# Requires: ffmpeg
+set -e
+
+SLATE_DIR="${1:-data/slate}"
+mkdir -p "$SLATE_DIR"
+
+SLATE_MP4="$SLATE_DIR/slate.mp4"
+SLATE_HLS="$SLATE_DIR/hls"
+mkdir -p "$SLATE_HLS"
+
+echo "=== Generating Emergency Slate ==="
+
+# 1. Generate 10s slate video: color bars + "We'll Be Right Back" text
+echo "[1/3] Generating slate video (10s, H.264/AAC, 30fps, 2s keyframes)..."
+ffmpeg -y -f lavfi -i "color=c=#1a1a2e:s=1280x720:d=10:r=30" \
+       -f lavfi -i "sine=frequency=440:duration=10" \
+       -filter_complex "[0]drawtext=text='Linear Void':fontcolor=#587792:fontsize=60:x=(w-text_w)/2:y=(h-text_h)/2-40,drawtext=text='We'\''ll Be Right Back':fontcolor=#ede8e6:fontsize=36:x=(w-text_w)/2:y=(h-text_h)/2+30[bg];[1]volume=0.15[a]" \
+       -map "[bg]" -map "[a]" \
+       -c:v libx264 -preset medium -crf 21 \
+       -r 30 -g 60 -keyint_min 60 -sc_threshold 0 \
+       -pix_fmt yuv420p \
+       -c:a aac -b:a 128k -ar 48000 -ac 2 \
+       -movflags +faststart \
+       -t 10 \
+       "$SLATE_MP4"
+
+echo "   Slate MP4: $(du -h "$SLATE_MP4" | cut -f1)"
+
+# 2. Verify slate meets normalization profile
+echo "[2/3] Verifying slate normalization..."
+ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate,pix_fmt,sample_rate \
+        -of default=noprint_wrappers=1 "$SLATE_MP4" 2>&1 | head -10
+
+# 3. Package as pre-rendered HLS (fMP4, 6s segments)
+echo "[3/3] Packaging as HLS..."
+ffmpeg -y -i "$SLATE_MP4" \
+       -c copy \
+       -f hls \
+       -hls_time 6 \
+       -hls_list_size 5 \
+       -hls_segment_type fmp4 \
+       -hls_fmp4_init_filename "init.mp4" \
+       -hls_flags "independent_segments" \
+       -hls_segment_filename "$SLATE_HLS/slate_segment_%03d.m4s" \
+       "$SLATE_HLS/slate.m3u8"
+
+echo ""
+echo "=== Slate Generated ==="
+echo "  MP4:      $SLATE_MP4"
+echo "  Manifest: $SLATE_HLS/slate.m3u8"
+echo "  Segments: $(find "$SLATE_HLS" -name '*.m4s' | wc -l) files"
+echo "  Init:     $SLATE_HLS/init.mp4"
+echo ""
+echo "To use: mount $SLATE_HLS as /app/slate in playout container"

scripts/normalize.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# Normalize video to Linear Void required profile.
+# Output: H.264/AAC, 30fps constant, 2s keyframes, yuv420p, 48kHz audio.
+# Usage: ./normalize.sh <input> [output]
+set -e
+
+INPUT="$1"
+if [ -z "$INPUT" ]; then
+  echo "Usage: $0 <input-file> [output-file]"
+  echo "  Normalizes video to Linear Void profile: H.264/AAC, 30fps, 2s keyframes"
+  exit 1
+fi
+
+if [ ! -f "$INPUT" ]; then
+  echo "Error: input file not found: $INPUT"
+  exit 1
+fi
+
+OUTPUT="${2:-${INPUT%.*}-normalized.mp4}"
+CRF="${NORMALIZE_CRF:-21}"
+PRESET="${NORMALIZE_PRESET:-medium}"
+AUDIO_BITRATE="${NORMALIZE_AUDIO_BITRATE:-160k}"
+
+echo "=== Linear Void Video Normalization ==="
+echo "  Input:       $INPUT ($(du -h "$INPUT" | cut -f1))"
+echo "  Output:      $OUTPUT"
+echo "  CRF:         $CRF"
+echo "  Preset:      $PRESET"
+echo "  Audio rate:  $AUDIO_BITRATE"
+echo ""
+
+# Probe input
+echo "--- Input Properties ---"
+ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate,pix_fmt,sample_rate,channels \
+        -of default=noprint_wrappers=1 "$INPUT" 2>&1
+echo ""
+
+# Normalize
+echo "--- Normalizing ---"
+ffmpeg -y -i "$INPUT" \
+  -c:v libx264 -preset "$PRESET" -crf "$CRF" \
+  -r 30 -g 60 -keyint_min 60 -sc_threshold 0 \
+  -pix_fmt yuv420p \
+  -c:a aac -b:a "$AUDIO_BITRATE" -ar 48000 -ac 2 \
+  -movflags +faststart \
+  "$OUTPUT"
+
+echo ""
+echo "--- Output Properties ---"
+ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate,pix_fmt,sample_rate,channels \
+        -of default=noprint_wrappers=1 "$OUTPUT" 2>&1
+echo ""
+
+echo "=== Normalization Complete ==="
+echo "  Output: $OUTPUT ($(du -h "$OUTPUT" | cut -f1))"
+echo ""
+echo "Verify with: ffprobe -v error -show_entries stream=codec_name,r_frame_rate,pix_fmt -of default=noprint_wrappers=1 $OUTPUT"

scripts/test-playout-e2e.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# End-to-end playout test: single file → 3-file playlist → verify seamless transition
+# Requires: Docker, ffprobe, curl. Run from repo root.
+set -e
+
+echo "=== Playout End-to-End Test ==="
+
+# 1. Build playout image
+echo "[1/7] Building playout image..."
+docker compose build playout
+
+# 2. Create test playlist with 3 demo files (reuse demodata if exists)
+TEST_PLAYLIST="data/playlist/playlist.txt"
+mkdir -p data/playlist data/hls
+
+echo "[2/7] Creating 3-file test playlist..."
+cat > "$TEST_PLAYLIST" << 'EOF'
+file '/app/media/demo1.mp4'
+file '/app/media/demo2.mp4'
+file '/app/media/demo1.mp4'
+EOF
+echo "Playlist created with 3 entries:"
+cat "$TEST_PLAYLIST"
+
+# 3. Validate playlist parses correctly
+echo "[3/7] Validating playlist parse..."
+LINE_COUNT=$(grep -c "^file " "$TEST_PLAYLIST" || true)
+if [ "$LINE_COUNT" -ne 3 ]; then
+  echo "FAIL: Expected 3 entries, got $LINE_COUNT"
+  exit 1
+fi
+echo "OK: $LINE_COUNT entries parsed"
+
+# 4. Start playout container
+echo "[4/7] Starting playout container..."
+docker compose up -d playout
+sleep 8
+
+# 5. Verify health endpoint
+echo "[5/7] Checking playout health..."
+HEALTH=$(curl -sf http://localhost:8081/health || echo "FAIL")
+if echo "$HEALTH" | grep -q "healthy"; then
+  echo "OK: Health endpoint: $HEALTH"
+else
+  echo "FAIL: Health check returned: $HEALTH"
+  docker compose logs playout --tail 30
+  exit 1
+fi
+
+# 6. Verify HLS output
+echo "[6/7] Verifying HLS output..."
+sleep 10  # Let FFmpeg produce some segments
+
+if [ -f "data/hls/playlist.m3u8" ]; then
+  echo "OK: playlist.m3u8 exists"
+  MANIFEST_LINES=$(wc -l < data/hls/playlist.m3u8)
+  echo "   Manifest lines: $MANIFEST_LINES"
+else
+  echo "FAIL: No playlist.m3u8 generated"
+  docker compose logs playout --tail 30
+  exit 1
+fi
+
+SEGMENT_COUNT=$(find data/hls -name "segment_*.m4s" | wc -l)
+if [ "$SEGMENT_COUNT" -ge 1 ]; then
+  echo "OK: $SEGMENT_COUNT segment(s) generated"
+else
+  echo "FAIL: No segments generated"
+  exit 1
+fi
+
+# 7. Check for seamless transition markers (no FFmpeg errors in logs)
+echo "[7/7] Checking for seamless transitions..."
+ERRORS=$(docker compose logs playout 2>&1 | grep -ci "error" || true)
+if [ "$ERRORS" -eq 0 ]; then
+  echo "OK: No FFmpeg errors in logs"
+else
+  echo "WARN: $ERRORS error(s) in playout logs (may be R2 connection — check manually)"
+fi
+
+echo ""
+echo "=== Playout E2E Test PASSED ==="
+echo "Verified: playlist parse → HLS generation → health endpoint → segment output"
+echo ""
+echo "Cleanup: docker compose down playout"

scripts/verify-backups.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Weekly backup integrity verification.
+# Downloads latest backup from R2, restores into temp container, runs sanity checks.
+# Schedule: cron weekly (after weekly backup).
+set -e
+
+R2_BUCKET="${R2_BUCKET:-linearvoid-backups}"
+TEMP_DIR=$(mktemp -d)
+trap "rm -rf $TEMP_DIR" EXIT
+
+echo "[$(date -Iseconds)] Starting backup integrity verification..."
+
+# Download latest weekly backup from R2
+if [ -z "$R2_ENDPOINT" ] || [ -z "$R2_ACCESS_KEY_ID" ]; then
+    echo "  SKIP: R2 credentials not configured (R2_ENDPOINT, R2_ACCESS_KEY_ID)"
+    exit 0
+fi
+
+LATEST=$(aws s3 ls "s3://${R2_BUCKET}/weekly/" --endpoint-url "$R2_ENDPOINT" --no-verify-ssl 2>/dev/null | sort | tail -1 | awk '{print $4}')
+if [ -z "$LATEST" ]; then
+    echo "  SKIP: No weekly backups found in R2"
+    exit 0
+fi
+
+echo "  Downloading: $LATEST"
+aws s3 cp "s3://${R2_BUCKET}/weekly/${LATEST}" "$TEMP_DIR/backup.dump" \
+    --endpoint-url "$R2_ENDPOINT" --no-verify-ssl 2>/dev/null
+
+echo "  File size: $(du -h "$TEMP_DIR/backup.dump" | cut -f1)"
+
+# Restore into temp PostgreSQL container
+echo "  Starting temp PostgreSQL..."
+docker run -d --name lv-backup-test-$$ \
+    -e POSTGRES_PASSWORD=test \
+    -e POSTGRES_DB=linearvoid \
+    -p 15432:5432 \
+    postgres:15-alpine 2>/dev/null
+
+sleep 5
+
+# Wait for PG to be ready
+for i in $(seq 1 10); do
+    if docker exec lv-backup-test-$$ pg_isready -U postgres 2>/dev/null; then
+        break
+    fi
+    sleep 2
+done
+
+# Restore
+echo "  Restoring backup..."
+docker cp "$TEMP_DIR/backup.dump" "lv-backup-test-$$:/tmp/backup.dump"
+docker exec lv-backup-test-$$ pg_restore -U postgres -d linearvoid /tmp/backup.dump 2>/dev/null && \
+    echo "  Restore: OK" || { echo "  Restore: FAILED"; docker rm -f lv-backup-test-$$ 2>/dev/null; exit 1; }
+
+# Sanity checks
+MSG_COUNT=$(docker exec lv-backup-test-$$ psql -U postgres -d linearvoid -tAc "SELECT COUNT(*) FROM messages;" 2>/dev/null || echo "0")
+MOD_COUNT=$(docker exec lv-backup-test-$$ psql -U postgres -d linearvoid -tAc "SELECT COUNT(*) FROM moderation_logs;" 2>/dev/null || echo "0")
+echo "  Messages: $MSG_COUNT, Moderation: $MOD_COUNT"
+
+# Cleanup
+docker rm -f lv-backup-test-$$ 2>/dev/null
+
+echo "[$(date -Iseconds)] Backup verification complete. OK."