# 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
- [x] No new tables.
- [x] Requires complex aggregation queries on the `transactions` table.

### API / Interface
- [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.
- **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. [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
- [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.