feat: implement visual analytics and activity charts

tickets/2026-01-08-dashboard-activity-charts.md

@@ -1,6 +1,6 @@
 # DASH-003: Visual Analytics & Activity Charts
 
-**Status:** Draft
+**Status:** Done
 **Created:** 2026-01-08
 **Tags:** dashboard, analytics, charts, frontend
 
@@ -11,12 +11,12 @@
 
 ## 2. Technical Requirements
 ### Data Model Changes
-- [ ] No new tables.
-- [ ] Requires complex aggregation queries on the `transactions` table.
+- [x] No new tables.
+- [x] 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 }>`.
+- [x] `GET /api/stats/activity`: Returns an array of data points for the last 24 hours (hourly granularity).
+- [x] 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.
@@ -27,12 +27,35 @@
     - 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.
+1. [x] **Given** a 24-hour history of transactions, **When** the dashboard loads, **Then** a line or area chart displays the command volume over time.
+2. [x] **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. [x] **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 (e.g., `recharts` or `lucide-react` compatible library).
-- [ ] Step 4: Implement the `ActivityChart` component into the middle column of the dashboard.
+- [x] Step 1: Add an aggregation method to `dashboard.service.ts` to fetch hourly counts from the `transactions` table.
+- [x] Step 2: Create the `/api/stats/activity` endpoint.
+- [x] Step 3: Install a charting library (`recharts`).
+- [x] 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.