discord-rpg-concept/tickets/2026-01-08-dashboard-real-data-integration.md

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:

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)