feat: integrate real data into dashboard

- Created dashboard service with DB queries for users, economy, events - Added client stats provider with 30s caching for Discord metrics - Implemented /api/stats endpoint aggregating all dashboard data - Created useDashboardStats React hook with auto-refresh - Updated Dashboard.tsx to display real data with loading/error states - Added comprehensive test coverage (11 tests passing) - Replaced all mock values with live Discord and database metrics
2026-01-08 18:50:44 +01:00
parent a207d511be
commit 17cb70ec00
10 changed files with 861 additions and 35 deletions
--- a/tickets/2026-01-08-dashboard-real-data-integration.md
+++ b/tickets/2026-01-08-dashboard-real-data-integration.md
@@ -0,0 +1,168 @@
+# DASH-001: Dashboard Real Data Integration
+
+**Status:** Draft
+**Created:** 2026-01-08
+**Tags:** dashboard, api, discord-client, database, real-time
+
+## 1. Context & User Story
+* **As a:** Bot Administrator
+* **I want to:** See real data on the dashboard instead of mock/hardcoded values
+* **So that:** I can monitor actual bot metrics, user activity, and system health in real-time
+
+## 2. Technical Requirements
+
+### Data Model Changes
+- [ ] No new tables required
+- [ ] SQL migration required? **No** – existing schema already has `users`, `transactions`, `moderationCases`, and other relevant tables
+
+### API / Interface
+
+#### New Dashboard Stats Service
+Create a new service at `shared/modules/dashboard/dashboard.service.ts`:
+
+```typescript
+interface DashboardStats {
+  guilds: {
+    count: number;
+    changeFromLastMonth?: number;
+  };
+  users: {
+    active: number;
+    changePercentFromLastMonth?: number;
+  };
+  commands: {
+    total: number;
+    changePercentFromLastMonth?: number;
+  };
+  ping: {
+    avg: number;
+    changeFromLastHour?: number;
+  };
+  recentEvents: RecentEvent[];
+  activityOverview: ActivityDataPoint[];
+}
+
+interface RecentEvent {
+  type: 'success' | 'error' | 'info';
+  message: string;
+  timestamp: Date;
+}
+```
+
+#### API Endpoints
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/stats` | Returns `DashboardStats` object |
+| `GET` | `/api/stats/realtime` | WebSocket/SSE for live updates |
+
+### Discord Client Data
+
+The `AuroraClient` (exported from `bot/lib/BotClient.ts`) provides access to:
+
+| Property | Data Source | Dashboard Metric |
+|----------|-------------|------------------|
+| `client.guilds.cache.size` | Discord.js | Total Servers |
+| `client.users.cache.size` | Discord.js | Active Users (approximate) |
+| `client.ws.ping` | Discord.js | Avg Ping |
+| `client.commands.size` | Bot commands | Commands Registered |
+| `client.lastCommandTimestamp` | Custom property | Last command run time |
+
+### Database Data
+
+Query from existing tables:
+
+| Metric | Query |
+|--------|-------|
+| User count (registered) | `SELECT COUNT(*) FROM users WHERE is_active = true` |
+| Commands executed (today) | `SELECT COUNT(*) FROM transactions WHERE type = 'COMMAND_RUN' AND created_at >= NOW() - INTERVAL '1 day'` |
+| Recent moderation events | `SELECT * FROM moderation_cases ORDER BY created_at DESC LIMIT 10` |
+| Recent transactions | `SELECT * FROM transactions ORDER BY created_at DESC LIMIT 10` |
+
+> [!IMPORTANT]
+> The Discord client instance (`AuroraClient`) is in the `bot` package, while the web server is in the `web` package. Need to establish cross-package communication:
+> - **Option A**: Export client reference from `bot` and import in `web` (same process, simple)
+> - **Option B**: IPC via shared memory or message queue (separate processes)
+> - **Option C**: Internal HTTP/WebSocket between bot and web (microservice pattern)
+
+## 3. Constraints & Validations (CRITICAL)
+
+- **Input Validation:** 
+  - API endpoints must not accept arbitrary query parameters
+  - Rate limiting on `/api/stats` to prevent abuse (max 60 requests/minute per IP)
+  
+- **System Constraints:**
+  - Discord API rate limits apply when fetching guild/user data
+  - Cache Discord data and refresh at most every 30 seconds
+  - Database queries should be optimized with existing indices
+  - API response timeout: 5 seconds maximum
+  
+- **Business Logic Guardrails:**
+  - Do not expose sensitive user data (only aggregates)
+  - Do not expose Discord tokens or internal IDs in API responses
+  - Activity history limited to last 24 hours to prevent performance issues
+  - User counts should count only registered users, not all Discord users
+
+## 4. Acceptance Criteria
+
+1. [ ] **Given** the dashboard is loaded, **When** the API `/api/stats` is called, **Then** it returns real guild count from Discord client
+2. [ ] **Given** the bot is connected to Discord, **When** viewing the dashboard, **Then** the "Total Servers" shows actual `guilds.cache.size`
+3. [ ] **Given** users are registered in the database, **When** viewing the dashboard, **Then** "Active Users" shows count from `users` table where `is_active = true`
+4. [ ] **Given** the bot is running, **When** viewing the dashboard, **Then** "Avg Ping" shows actual `client.ws.ping` value
+5. [ ] **Given** recent bot activity occurred, **When** viewing "Recent Events", **Then** events from `transactions` and `moderation_cases` tables are displayed
+6. [ ] **Given** mock data exists in components, **When** the feature is complete, **Then** all hardcoded values in `Dashboard.tsx` are replaced with API data
+
+## 5. Implementation Plan
+
+### Phase 1: Data Layer & Services
+- [ ] Create `shared/modules/dashboard/dashboard.service.ts` with statistics aggregation functions
+- [ ] Add helper to query active user count from database
+- [ ] Add helper to query recent transactions (as events)
+- [ ] Add helper to query moderation cases (as events)
+
+---
+
+### Phase 2: Discord Client Exposure
+- [ ] Create a client stats provider that exposes Discord metrics
+- [ ] Implement caching layer to avoid rate limiting (30-second TTL)
+- [ ] Export stats getter from `bot` package for `web` package consumption
+
+---
+
+### Phase 3: API Implementation
+- [ ] Add `/api/stats` endpoint in `web/src/server.ts`
+- [ ] Wire up `dashboard.service.ts` functions to API
+- [ ] Add error handling and response formatting
+- [ ] Consider adding rate limiting middleware
+
+---
+
+### Phase 4: Frontend Integration
+- [ ] Create custom React hook `useDashboardStats()` for data fetching
+- [ ] Replace hardcoded values in `Dashboard.tsx` with hook data
+- [ ] Add loading states and error handling
+- [ ] Implement auto-refresh (poll every 30 seconds or use SSE/WebSocket)
+
+---
+
+### Phase 5: Activity Overview Chart
+- [ ] Query hourly command/transaction counts for last 24 hours
+- [ ] Integrate charting library (e.g., Recharts, Chart.js)
+- [ ] Replace "Chart Placeholder" with actual chart component
+
+---
+
+## Architecture Decision Required
+
+> [!WARNING]
+> **Key Decision: How should the web server access Discord client data?**
+> 
+> The bot and web server currently run in the same process. Recommend:
+> - **Short term**: Direct import of `AuroraClient` singleton in API handlers
+> - **Long term**: Consider event bus or shared state manager if splitting to microservices
+
+## Out of Scope
+
+- User authentication/authorization for API endpoints
+- Historical data beyond 24 hours
+- Command execution tracking (would require new database table)
+- Guild-specific analytics (separate feature)