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