62 lines
3.3 KiB
Markdown
62 lines
3.3 KiB
Markdown
# 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.
|