discord-rpg-concept/tickets/2026-01-08-dashboard-activity-charts.md

DASH-003: Visual Analytics & Activity Charts

Status: Done Created: 2026-01-08 Tags: dashboard, analytics, charts, frontend

1. Context & User Story

• As a: Bot Administrator
• I want to: View a graphical representation of bot usage over the last 24 hours.
• So that: I can identify peak usage times and trends in command execution.

2. Technical Requirements

Data Model Changes

• No new tables.
• Requires complex aggregation queries on the transactions table.

API / Interface

• GET /api/stats/activity: Returns an array of data points for the last 24 hours (hourly granularity).
• Response Structure: Array<{ hour: string, commands: number, transactions: number }>.

3. Constraints & Validations (CRITICAL)

• Input Validation: Hourly buckets must be strictly validated for the 24h window.
• System Constraints:
  • Database query must be cached for at least 5 minutes as it involves heavy aggregation.
  • Chart must be responsive and handle mobile viewports.
• Business Logic Guardrails:
  • If no data exists for an hour, it must return 0 rather than skipping the point.

4. Acceptance Criteria

1. Given a 24-hour history of transactions, When the dashboard loads, Then a line or area chart displays the command volume over time.
2. Given the premium glassmorphic theme, When the chart is rendered, Then it must use the primary brand colors and gradients to match the UI.
3. Given a mouse hover on the chart, When hovering over a point, Then a glassmorphic tooltip shows exact counts for that hour.

5. Implementation Plan

• Step 1: Add an aggregation method to dashboard.service.ts to fetch hourly counts from the transactions table.
• Step 2: Create the /api/stats/activity endpoint.
• Step 3: Install a charting library (recharts).
• Step 4: Implement the ActivityChart component into the middle column of the dashboard.

Implementation Notes

Implemented a comprehensive activity analytics system for the Aurora dashboard:

Backend Changes

• Service Layer: Added getActivityAggregation to dashboard.service.ts. It performs a hourly aggregation on the transactions table using Postgres date_trunc and FILTER clauses to differentiate between "commands" and "total transactions". Missing hours in the 24h window are automatically filled with zero-values.
• API: Implemented GET /api/stats/activity in web/src/server.ts with a 5-minute in-memory cache to maintain server performance.

Frontend Changes

• Library: Added recharts for high-performance SVG charting.
• Hooks: Created use-activity-stats.ts to manage the lifecycle and polling of analytics data.
• Components: Developed ActivityChart.tsx featuring:
  • Premium glassmorphic styling (backdrop blur, subtle borders).
  • Responsive AreaChart with brand-matching gradients.
  • Custom glassmorphic tooltip with precise data point values.
  • Smooth entry animations.
• Integration: Placed the new analytics card prominently in the Dashboard.tsx layout.

Verification

• Unit Tests: Added comprehensive test cases to dashboard.service.test.ts verifying the 24-point guaranteed response and correct data mapping.
• Type Safety: Passed bun x tsc --noEmit with zero errors.
• Runtime: All tests passing.