forked from syntaxbullet/AuroraBot-discord
44 lines
2.2 KiB
Markdown
44 lines
2.2 KiB
Markdown
# 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.
|