102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
# 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-001.md), [ADR-002](./ADR-002-module-structure.md), [ADR-003](./ADR-003-tech-stack.md)
|
||
|
||
## 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.
|