Management Webinterface

[karaktaka]

Enhancement: Management Web Interface

A web dashboard for managing all bot settings per guild — mirrors everything configurable via slash/prefix commands, with Discord OAuth2 authentication and role-based access. Bot operators additionally get health monitoring. Also serves as the authenticated webhook receiver for external integrations (Twitch, etc.).

Priority: High

---

Phase 1 — Backend API + Auth

Authentication

• Discord OAuth2 login — users authenticate with their Discord account
• Bot fetches the user's guilds and roles via Discord API
• Role-based access: only users with admin/mod permissions in a guild can manage that guild's settings
• Bot operators (from config.yaml ops list) get access to monitoring/health endpoints

API Backend

• FastAPI REST API as a separate service (own Docker target)
• Shares the database with the bot (reads/writes the same SQLAlchemy models)
• Endpoints mirror existing bot settings: prefixes, module toggles, points config, etc.
• OpenAPI/Swagger docs auto-generated

Endpoints (Phase 1)

• GET/PUT /api/guilds/{id}/settings — General guild settings (prefix, enabled modules)
• GET/PUT /api/guilds/{id}/points — Points configuration (values, cooldowns, role rewards)
• GET/PUT /api/guilds/{id}/moderation — Auto-delete, auto-kick settings
• GET/PUT /api/guilds/{id}/roles — Reaction roles, bot moderator role
• GET /api/guilds/{id}/leaderboard — Points leaderboard data
• GET /api/health — Bot health metrics (operator only)

---

Phase 2 — Frontend SPA

Tech Stack

• Modern SPA framework (Vue/React/Svelte — TBD during implementation) + Vite
• Responsive design (usable on mobile)
• Component library for consistent UI

Dashboard Views

• Guild selector — Pick which guild to manage (only shows guilds the user has permissions for)
• Settings panel — View current settings and defaults, toggle/edit values
• Leaderboard — View points standings per guild
• Applications — View/manage application forms and submissions (once Applications #81 is implemented)
• Tournaments — View active tournaments and brackets (once Tournaments #79 is implemented)

---

Phase 3 — Operator Monitoring

Health Dashboard (operators only)

• Bot uptime, latency, connected guilds count
• Memory/CPU usage
• Error log viewer (recent errors)
• Module status (loaded/unloaded per guild)
• Connected voice channels

---

Phase 4 — Webhook Listener

Authenticated Webhook Receiver

The web service acts as the ingestion point for external webhooks (e.g., Twitch EventSub, GitHub, etc.).

• Authentication: Incoming webhooks validated via HMAC signature verification (per-provider secret)
• Event routing: Received events are written to a shared DB queue/table; the bot polls or picks them up for Discord notifications
• Twitch integration (planned feature): Twitch EventSub webhooks for stream go-live notifications, subscriber events, etc.
• Extensible: Provider-agnostic design — new webhook sources can be added by registering a handler + secret

Admin Configuration

• Admins configure which webhook events their guild subscribes to (via dashboard or bot commands)
• Per-guild notification channel selection

---

Deployment

• Separate Docker build target alongside bot and migrations
• Frontend built as static assets, served by the API or a reverse proxy
• Shares the existing database — no additional DB required
• Must be publicly reachable for webhook callbacks (Twitch, etc.)
• Environment config for OAuth2 client ID/secret, API URL, and webhook secrets

Technical Notes

• FastAPI backend in a new top-level directory (e.g., web/ or dashboard/)
• Reuses NerdyPy/models/ for database access (shared SQLAlchemy models)
• Discord OAuth2 flow via authlib or httpx + manual token exchange
• JWT or session-based auth for API requests after OAuth2 login
• CORS configuration for SPA ↔ API communication
• Bot ↔ Web service communication via shared DB (webhook events table that bot consumes)

[karaktaka]

Phase 4 (Webhook Listener) is a dependency for #169 (Twitch Stream Notifications) — first consumer of the webhook infrastructure.