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

DASH-002: Real-time Live Updates via WebSockets

Status: Done 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.
• Created shared/lib/events.ts for a global system event bus.

API / Interface

• Establish a WebSocket endpoint at /ws.
• Define the message protocol:
  • STATS_UPDATE: Server to client containing full DashboardStats.
  • NEW_EVENT: Server to client when a specific event is recorded.

3. Constraints & Validations (CRITICAL)

• Input Validation: WS messages validated using JSON parsing and type checks.
• System Constraints:
  • WebSocket broadcast interval set to 5s for metrics.
  • Automatic reconnection logic handled in the frontend hook.
• Business Logic Guardrails:
  • Events are pushed immediately as they occur via the system event bus.

4. Acceptance Criteria

1. Given the dashboard is open, When a command is run in Discord (e.g. Daily), 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 into web/src/server.ts using Bun's native websocket support.
• Step 2: Implement a broadcast system in dashboard.service.ts to push events to the WS handler using systemEvents.
• Step 3: Create/Update useDashboardStats hook in the frontend to handle connection lifecycle and state merging.
• Step 4: Refactor Dashboard.tsx state consumption to benefit from real-time updates.

Implementation Notes

Files Changed

• shared/lib/events.ts: New event bus for the system.
• web/src/server.ts: Added WebSocket handler and stats broadcast.
• web/src/hooks/use-dashboard-stats.ts: Replaced polling with WebSocket + HTTP initial load.
• shared/modules/dashboard/dashboard.service.ts: Added recordEvent helper to emit WS events.
• shared/modules/economy/economy.service.ts: Integrated recordEvent into daily claims and transfers.
• shared/modules/dashboard/dashboard.service.test.ts: Added unit tests for event emission.