linearvoid/.github/instructions/BACKLOG.md

BACKLOG

Status reflects 2026-08-06 code scan + implementation batches.

Playout & Delivery

• Implement FFmpeg + MediaMTX/SRS continuous HLS playout from playlist
• Implement immutable HLS segment naming for cache-friendly delivery
• Upload HLS segments to Cloudflare R2 via S3-compatible API
• Implement emergency slate fallback on playout failure
• Auto-restart loop for FFmpeg/MediaMTX on failure

Video Normalization

• Implement video normalization pipeline (H.264/AAC, 30 fps, 2 s keyframes)
• Implement ffprobe verification gate rejecting non-conforming files
• Enforce normalization check before upload acceptance in admin UI

Chat Service

• Implement WebSocket chat backend (Go) with room fan-out
• Implement private DM channel routing
• Implement Redis presence tracking for chat
• Implement Redis pub/sub for multi-instance chat
• Implement Redis rate limiting (INCR + EXPIRE windowing, >10/10s throttle)
• Implement chat message persistence (SQLite v1, PostgreSQL migration path)
• Implement moderation commands (/mod, /mute, /ban) in backend
• Implement moderation audit log persistence
• Implement graceful degradation when Redis unavailable (core chat remains up)

Frontend — Viewer SPA

• Build static SPA with hls.js player integration
• Build chat sidebar UI (public rooms + private DMs)
• Implement schedule metadata display synced with playlist timeline
• Implement responsive/mobile-friendly viewer layout

Frontend — Admin Interfaces

• Build admin login page with session authentication
• Build admin dashboard overview page
• Build video upload interface with chunked upload support
• Build playlist management interface (drag-to-reorder, validation warnings)
• Build schedule override/management interface (CRUD + conflict detection)
• Build user management interface (mute/unmute/ban/unban actions)
• Build moderation dashboard (chat log, inline mod actions, CSV export)
• Build analytics dashboard (time range selector)
• Build system configuration/status page (config editor, restart buttons)

Infrastructure — nginx

• Configure nginx reverse proxy with auth_request for admin paths
• Configure nginx HLS path with CORS headers + OPTIONS preflight
• Configure nginx WebSocket upgrade forwarding for /ws
• Configure nginx health endpoints (/health JSON, stub_status)

Infrastructure — Docker

• Create Dockerfiles for playout, chat, nginx services
• Create docker-compose.yml for all services (11 containers)
• Create docker-compose.prod.yml override for production

Infrastructure — CI/CD (Gitea Actions)

• Implement CI workflow (lint, build, vet, push images)
• Implement CD workflow (pull, deploy, health checks — IP-agnostic)
• Generate .env from Gitea secrets in CD workflow
• Seed Prometheus config + alerts into named volume during deploy
• Implement health check validation with retry in CD pipeline

Cloudflare Configuration

• Configure DNS for linearvoid.tv apex and www redirect (manual)
• Configure media.linearvoid.tv for split-domain HLS delivery (manual)
• Create R2 bucket (manual)
• Configure Cache Rules: .ts/.m4s + .m3u8 (manual)
• Configure Cloudflare Pages (manual)
• Enable Tiered Cache, WAF, rate limiting (manual)
• Implement Worker for immutable cache headers on segment paths
• Enforce HTTPS/WSS, redirect HTTP → HTTPS (manual)

Monitoring & Observability

• Set up Prometheus with chat/playout/nginx/redis/postgres/node scrape targets
• Add nginx-exporter, redis-exporter, postgres-exporter, node-exporter
• Import Grafana app + operational dashboards
• Define Prometheus alerting rules (8 rules: ChatDown, PlayoutDown, RedisDown, etc.)
• Set up UptimeRobot external monitoring

Security

• Implement admin cookie-session auth (HttpOnly, SameSite=Strict, Secure when TLS)
• Implement server-side session expiration
• Enforce HTTPS/WSS at edge and origin
• Implement rate limiting for chat messages (Redis windowing)
• Implement WebSocket connection rate limiting (5/IP/60s)
• Implement admin login rate limiting (5/IP/5min)

Data & Storage

• Set up PostgreSQL/SQLite for chat history and moderation data
• Set up Redis with append-only persistence + maxmemory policy
• Implement daily Postgres backups to R2 (14-day retention)
• Implement weekly full backup snapshots (8-week retention)
• Implement backup integrity verification (restore test)
• Document and rehearse recovery runbook (quarterly drill)

Scaling & Performance

• Optimize segment immutability and manifest TTL for cache efficiency
• Measure playback TTFB from multiple US regions
• Load-test WebSocket connections
• Benchmark admin API p95 latency
• Track cache hit ratio and R2 ops in production
• Capacity trigger monitoring
• Plan Phase 2 service separation
• Plan Phase 3 multi-origin resilience

Documentation

• Document API contracts in API.md
• Document deployment runbook in DEPLOYMENT.md
• Document monitoring setup in MONITORING.md
• Document security model in SECURITY.md
• Create incident runbook (docs/incident-runbook.md)
• Write Level 2/3 building block views