attune/work-summary/2026-02-26-entity-history-phase3-analytics.md

# Entity History Phase 3 — Analytics Dashboard

**Date**: 2026-02-26

## Summary

Implemented the final phase of the TimescaleDB entity history plan: continuous aggregates, analytics API endpoints, and dashboard visualization widgets. This completes the full history tracking pipeline from database triggers → hypertables → continuous aggregates → API → UI.

## Changes

### New Files

1. **`migrations/20260226200000_continuous_aggregates.sql`** — TimescaleDB continuous aggregates migration:
   - `execution_status_hourly` — execution status transitions per hour by action_ref and status
   - `execution_throughput_hourly` — execution creation volume per hour by action_ref
   - `event_volume_hourly` — event creation volume per hour by trigger_ref
   - `worker_status_hourly` — worker status transitions per hour by worker name
   - `enforcement_volume_hourly` — enforcement creation volume per hour by rule_ref
   - Auto-refresh policies: 30-min interval for most, 1-hour for workers; 7-day lookback window
   - Initial `CALL refresh_continuous_aggregate()` for all five views

2. **`crates/common/src/repositories/analytics.rs`** — Analytics repository:
   - Row types: `ExecutionStatusBucket`, `ExecutionThroughputBucket`, `EventVolumeBucket`, `WorkerStatusBucket`, `EnforcementVolumeBucket`, `FailureRateSummary`
   - `AnalyticsTimeRange` with `default()` (24h), `last_hours()`, `last_days()` constructors
   - Query methods for each aggregate (global and per-entity-ref variants)
   - `execution_failure_rate()` — derives failure percentage from terminal-state transitions
   - Unit tests for time range construction and failure rate math

3. **`crates/api/src/dto/analytics.rs`** — Analytics DTOs:
   - `AnalyticsQueryParams` (since, until, hours) with `to_time_range()` conversion
   - Response types: `DashboardAnalyticsResponse`, `ExecutionStatusTimeSeriesResponse`, `ExecutionThroughputResponse`, `EventVolumeResponse`, `WorkerStatusTimeSeriesResponse`, `EnforcementVolumeResponse`, `FailureRateResponse`
   - `TimeSeriesPoint` — universal (bucket, label, value) data point
   - `From` conversions from all repository bucket types to `TimeSeriesPoint`
   - Unit tests for query param defaults, clamping, explicit ranges, and conversions

4. **`crates/api/src/routes/analytics.rs`** — 7 API endpoints:
   - `GET /api/v1/analytics/dashboard` — combined payload (all metrics in one call, concurrent queries via `tokio::try_join!`)
   - `GET /api/v1/analytics/executions/status` — status transitions over time
   - `GET /api/v1/analytics/executions/throughput` — creation throughput over time
   - `GET /api/v1/analytics/executions/failure-rate` — failure rate summary
   - `GET /api/v1/analytics/events/volume` — event creation volume
   - `GET /api/v1/analytics/workers/status` — worker status transitions
   - `GET /api/v1/analytics/enforcements/volume` — enforcement creation volume
   - All endpoints: authenticated, utoipa-documented, accept `since`/`until`/`hours` query params

5. **`web/src/hooks/useAnalytics.ts`** — React Query hooks:
   - `useDashboardAnalytics()` — fetches combined dashboard payload (1-min stale, 2-min auto-refresh)
   - Individual hooks: `useExecutionStatusAnalytics()`, `useExecutionThroughputAnalytics()`, `useFailureRateAnalytics()`, `useEventVolumeAnalytics()`, `useWorkerStatusAnalytics()`, `useEnforcementVolumeAnalytics()`
   - Types: `DashboardAnalytics`, `TimeSeriesPoint`, `FailureRateSummary`, `TimeSeriesResponse`, `AnalyticsQueryParams`

6. **`web/src/components/common/AnalyticsWidgets.tsx`** — Dashboard visualization components:
   - `AnalyticsDashboard` — composite widget rendering all charts and metrics
   - `MiniBarChart` — pure-CSS bar chart with hover tooltips and adaptive x-axis labels
   - `StackedBarChart` — stacked bar chart for status breakdowns with auto-generated legend
   - `FailureRateCard` — SVG ring gauge showing success/failure/timeout breakdown
   - `StatCard` — simple metric card with icon, label, and value
   - `TimeRangeSelector` — segmented button group (6h, 12h, 24h, 2d, 7d)
   - No external chart library dependency — all visualization is pure CSS/SVG

### Modified Files

7. **`crates/common/src/repositories/mod.rs`** — Registered `analytics` module, re-exported `AnalyticsRepository`

8. **`crates/api/src/dto/mod.rs`** — Registered `analytics` module, re-exported key DTO types

9. **`crates/api/src/routes/mod.rs`** — Registered `analytics` module, re-exported `analytics_routes`

10. **`crates/api/src/server.rs`** — Merged `analytics_routes()` into the API v1 router

11. **`web/src/pages/dashboard/DashboardPage.tsx`** — Added `AnalyticsDashboard` widget below existing metrics/activity sections with `TimeRangeHours` state management

12. **`docs/plans/timescaledb-entity-history.md`** — Marked Phase 2 continuous aggregates and Phase 3 analytics items as ✅ complete

13. **`AGENTS.md`** — Updated development status (continuous aggregates + analytics in Complete, removed from Planned)

## Design Decisions

- **Combined dashboard endpoint**: `GET /analytics/dashboard` fetches all 6 aggregate queries concurrently with `tokio::try_join!`, returning everything in one response. This avoids 6+ waterfall requests from the dashboard page.
- **No chart library**: All visualization uses pure CSS (flex-based bars) and inline SVG (ring gauge). This avoids adding a heavy chart dependency for what are essentially bar charts and a donut. A dedicated charting library can be introduced later if more sophisticated visualizations are needed.
- **Time range selector**: The dashboard defaults to 24 hours and offers 6h/12h/24h/2d/7d presets. The `hours` query param provides a simpler interface than specifying ISO timestamps for the common case.
- **Auto-refresh**: The dashboard analytics hook has `refetchInterval: 120000` (2 minutes) so the dashboard stays reasonably current without hammering the API. The continuous aggregates themselves refresh every 30 minutes on the server side.
- **Stale time**: Analytics hooks use 60-second stale time since the underlying aggregates only refresh every 30 minutes — there's no benefit to re-fetching more often.
- **Continuous aggregate refresh policies**: 30-minute schedule for execution/event/enforcement aggregates (higher expected volume), 1-hour for workers (low volume). All with a 1-hour `end_offset` to avoid refreshing the currently-filling bucket, and 7-day `start_offset` to limit refresh scope.

## Remaining (not in scope)

- **Configurable retention periods via admin settings** — retention policies are set in the migration; admin UI for changing them is deferred
- **Export/archival to external storage** — deferred to a future phase