# DASH-003: Visual Analytics & Activity Charts

**Status:** Draft
**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 (e.g., `recharts` or `lucide-react` compatible library).
- [ ] Step 4: Implement the `ActivityChart` component into the middle column of the dashboard.