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

# 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.