discord-rpg-concept/tickets/2026-01-08-real-time-dashboard-updates.md

DASH-002: Real-time Live Updates via WebSockets

Status: Draft Created: 2026-01-08 Tags: dashboard, websocket, real-time, performance

1. Context & User Story

• As a: Bot Administrator
• I want to: See metrics and events update instantly on my screen without refreshing or waiting for polling intervals.
• So that: I can react immediately to errors or spikes in latency and have a dashboard that feels "alive."

2. Technical Requirements

Data Model Changes

• No database schema changes required.
• Redis or an in-memory event emitter might be useful for broadcasting events.

API / Interface

• Establish a WebSocket endpoint at /ws/stats.
• Define the message protocol:
  • HEARTBEAT: Client to server to keep connection alive.
  • STATS_UPDATE: Server to client containing partial or full DashboardStats.
  • NEW_EVENT: Server to client when a transaction or moderation case occurs.

3. Constraints & Validations (CRITICAL)

• Input Validation: WS messages must be validated using Zod.
• System Constraints:
  • Limit to 10 concurrent WS connections to prevent server strain.
  • Maximum message size: 16KB.
  • Connection timeout: 60s of inactivity triggers a disconnect.
• Business Logic Guardrails:
  • Websocket updates should not exceed 1 update per second for metrics.
  • Events are pushed immediately as they occur.

4. Acceptance Criteria

1. Given the dashboard is open, When a command is run in Discord, Then the "Recent Events" list updates instantly on the web UI.
2. Given a changing network environment, When the bot's ping fluctuates, Then the "Avg Latency" card updates in real-time.
3. Given a connection loss, When the network returns, Then the client automatically reconnects to the WS room.

5. Implementation Plan

• Step 1: Integrate a WebSocket library (e.g., bun's native ws or socket.io) into web/src/server.ts.
• Step 2: Implement a broadcast system in dashboard.service.ts to push events to the WS handler.
• Step 3: Create a useDashboardSocket hook in the frontend to handle connection lifecycle.
• Step 4: Refactor Dashboard.tsx to prefer WebSocket data over periodic polling.