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

ADR-004: Video Admin Web Interface (Upload, Playlist Management, Schedule Overrides)

Status: Proposed
Date: 2026-08-02
Author: AI Assistant (following AGENTS.md and ADR-002/ADR-003)
Related ADRs: ADR-001, ADR-002, ADR-003

Context

The system requires an administrative interface for content owners to:

• Upload new video files (with automatic normalization validation).
• Manage the playlist (add, remove, reorder, preview).
• Override the schedule (insert emergency slate, change start times).
• View current playout status and logs.
• Enforce normalization rules from ADR-001 before files are added to the playlist.

This interface must be lightweight, secure, and integrated with the playout service and Cloudflare R2. It should follow the "update documentation first" rule and the folder structure from ADR-002.

Decision Drivers

1. Lightweight & Maintainable – Prefer server-rendered or minimal JS (HTMX + Tailwind) over heavy SPA frameworks to align with ADR-003's "lightweight" principle.
2. Security – Strict authentication, file type/size validation, and R2 upload permissions.
3. Usability – Drag-and-drop playlist editor, progress indicators for normalization and upload, real-time playout status.
4. Integration – Must call playout service APIs for validation and playlist updates; upload directly to R2 with metadata.
5. Traceability – All admin actions must be logged for moderation/audit (future ADR-005).

Decision

Create a dedicated admin web interface in a new frontend/admin/ directory (or under a protected route in the main SPA).

Tech Stack (per ADR-003):

• Frontend: HTMX + Tailwind CSS + Alpine.js (minimal JS, server-rendered HTML). Alternative: React if complex interactions are needed later.
• Backend: Go (or Node.js) API endpoints exposed by the playout service or a dedicated backend/admin/ service.
• Authentication: JWT or session-based (admin roles only). Use Cloudflare Access or simple OAuth for production.
• File Handling: Upload → validate with ffprobe (codec, fps, keyframes, duration) → normalize if needed → store in R2 with metadata.
• Playlist Editor: Drag-and-drop UI that updates a shared playlist file or database record used by the playout worker.

UI Layout:

• Sidebar navigation (Dashboard, Upload, Playlist, Schedule, Logs).
• Upload page with progress bar, normalization report, and "Add to Playlist" button.
• Playlist page with reorderable list, preview thumbnails, and "Apply to Live" button.
• Live status dashboard showing current segment, next video, and playout health.
• Schedule override form for inserting emergency content.

Folder Placement (per ADR-002):

• frontend/admin/ – Admin-specific HTML/JS components.
• backend/playout/internal/admin/ – API handlers (or new backend/admin/ service if complexity grows).
• Documentation and API specs added to docs/architecture/.

Rationale

• HTMX keeps the admin interface lightweight and aligns with the overall "no heavy frontend frameworks" philosophy from ADR-003.
• Early validation and normalization enforcement prevents playout errors (key requirement from ADR-001).
• 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:

• Content owners can manage the channel without SSH or direct server access.
• Normalization is enforced at upload time, reducing runtime errors.
• Clear separation of admin UI from public viewer SPA.

Negative / Risks:

• Additional attack surface (file uploads) – mitigate with strict validation, size limits, and virus scanning (future).
• Admin UI must be protected by strong auth (planned for ADR-005).
• Initial development effort for drag-and-drop playlist editor.

Alternatives Considered:

• Full React Admin (rejected – heavier than needed).
• Third-party tool (e.g., Directus or Strapi) – rejected for independence and to stay within the self-hosted lightweight stack.
• CLI-only admin – rejected for usability.

Implementation Plan

1. Create this ADR-004 (done).
2. Implement backend API endpoints in backend/playout/ for validation and playlist updates.
3. Build the HTMX-based admin UI in frontend/admin/.
4. Add authentication middleware.
5. Update docker-compose.yml to serve the admin interface (protected route).
6. Write tests for normalization validation.

Next ADR: ADR-005 (user management, moderation dashboard, analytics).

References

• ADR-001: Normalization requirements, HLS playout, R2 usage.
• ADR-002: Folder structure (admin UI belongs under frontend or a protected route).
• ADR-003: Lightweight frontend preference (HTMX/Tailwind over heavy frameworks).
• arc42 documentation: Building Block View (admin as part of the overall system).

This ADR ensures all admin interface decisions are documented before code is written.