Add Docker setup, .env.example, updated .gitignore/CHANGELOG and ADRs 004-007 + arc42 template

2026-08-02 16:05:18 +02:00
1 parent dafcec1303
commit 0785260689
@@ -0,0 +1,105 @@
+# ADR-005: Web Admin Interfaces for User Management, Moderation, and Analytics
+
+**Status:** Proposed  
+**Date:** 2026-08-02  
+**Author:** AI Assistant (following AGENTS.md, ADR-002, ADR-003, and ADR-004)  
+**Related ADRs:** [ADR-001](./ADR-001.md), [ADR-002](./ADR-002-module-structure.md), [ADR-003](./ADR-003-tech-stack.md), [ADR-004](./ADR-004-admin-video.md)
+
+## Context
+
+Building on ADR-004 (video admin interface), the system requires additional protected admin interfaces for:
+
+- **User Management**: View registered users, manage roles, ban/suspend accounts.
+- **Moderation Tools**: Real-time moderation dashboard, mute/timeout/ban users, review/delete messages, view moderation audit log.
+- **Analytics**: Basic dashboard showing concurrent viewers, chat activity, popular videos, cache hit ratio, R2 usage, and playout health metrics.
+
+These interfaces must be secure, auditable, and integrated with the chat backend, database, and monitoring systems. All admin actions must be logged for compliance and review.
+
+## Decision Drivers
+
+1. **Consistency** – Use the same lightweight tech stack decided in ADR-004 (HTMX + Tailwind + Alpine.js) to avoid introducing new frameworks.
+2. **Security & Auditability** – All actions must require admin authentication and be logged immutably.
+3. **Real-time Needs** – Moderation dashboard should show live chat activity (WebSocket integration).
+4. **Simplicity** – Analytics should use existing Prometheus/Grafana data where possible rather than building a duplicate system.
+5. **Separation of Concerns** – Video admin (ADR-004) and user/moderation/analytics admin should share a common admin layout but remain modular.
+
+## Decision
+
+Extend the admin interface started in ADR-004 with additional protected sections:
+
+**Tech Stack (consistent with ADR-003 and ADR-004)**:
+
+- **Frontend**: HTMX + Tailwind + Alpine.js for all admin pages. Shared layout with sidebar navigation.
+- **Backend**: Go API endpoints (protected by JWT/session middleware) in `backend/admin/` or extended from the chat/playout services.
+- **Authentication**: Role-based (admin, moderator, viewer). Use Cloudflare Access or JWT with short expiry for production.
+- **Data Sources**:
+  - User management: PostgreSQL queries.
+  - Moderation: Chat database + Redis for live bans.
+  - Analytics: Prometheus metrics (viewer count, cache hits, R2 ops) + custom queries on chat history.
+
+**UI Structure**:
+
+- Common admin layout (`/admin/` route, protected).
+- **Users** tab: Searchable table, role assignment, ban/unban actions.
+- **Moderation** tab: Live chat feed, quick mute/ban/report review, audit log with filters.
+- **Analytics** tab: Dashboard with charts (concurrent viewers, chat volume, top videos, cache hit ratio, storage usage). Embed Grafana panels where possible.
+
+**Folder Placement** (per ADR-002):
+
+- `frontend/admin/` – Reused and extended from ADR-004 (add moderation and analytics components).
+- `backend/admin/` – New module for admin-specific API handlers (or extend `backend/chat/` and `backend/playout/`).
+- API documentation and OpenAPI spec added to `docs/architecture/`.
+
+**Logging**: All admin actions (ban, delete message, schedule override) written to an immutable audit log table.
+
+## Rationale
+
+- Reusing HTMX/Tailwind from ADR-004 keeps the admin interface lightweight and consistent.
+- Centralizing admin functionality under `/admin/` reduces maintenance overhead.
+- 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**:
+
+- Unified admin experience for content, users, moderation, and analytics.
+- Strong audit trail for all privileged actions.
+- Real-time moderation capabilities integrated with the chat backend.
+
+**Negative / Risks**:
+
+- Admin interface becomes a larger attack surface – mitigate with strict rate limiting, IP allowlisting, and Cloudflare WAF.
+- Real-time moderation may increase load on the chat service (monitor Redis and WebSocket connections).
+- Analytics queries on large chat history could be expensive – use aggregation tables or limit retention (planned in future ADR).
+
+**Alternatives Considered**:
+
+- Separate admin SPA (React AdminJS) – rejected for consistency with ADR-004 and to avoid framework bloat.
+- Third-party moderation tools (e.g., Discourse moderation suite) – rejected to maintain full self-hosted control.
+- No analytics – rejected because operators need visibility into cache hit ratio, viewer count, and R2 costs.
+
+## Implementation Plan
+
+1. Create this ADR-005 (done).
+2. Extend the admin layout from ADR-004 with new tabs (Users, Moderation, Analytics).
+3. Implement backend API endpoints for user management, moderation actions, and metrics aggregation.
+4. Add WebSocket support for live moderation feed.
+5. Integrate Prometheus queries for analytics dashboard.
+6. Add comprehensive audit logging for all admin actions.
+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.
+- ADR-002: Folder structure – admin UI belongs under `frontend/admin/`.
+- ADR-003: Lightweight frontend (HTMX/Tailwind) and Go backend preference.
+- ADR-004: Video admin interface (shared layout and authentication approach).
+- arc42 documentation: Cross-cutting Concepts (security, monitoring) and Building Block View (admin as extension of the system).
+
+This completes the admin interface documentation phase. All decisions are now traceable before any code is written.