---
name: dashboard-feature
description: Summary dashboard with KPI cards, recent activity, and charts.
---

# Blueprint: Dashboard Feature

## Frontend

- Route: `/dashboard`. Layout grid: KPI cards + 1–2 charts + recent activity list.
- Components: `PageHeader`, `SectionCard`, `StatusBadge`, `GlassCard`, ApexCharts wrapper.
- Data: server-aggregated DTOs — not raw entities.

## Backend

- `GetDashboardSummaryQuery` returning a single DTO with all KPIs (one round-trip).
- Cache the result for ~60s in Redis keyed by `tenantId + userId`.

## Database

- Indexes that support `WHERE tenantId = ? AND createdAt >= ?` for the activity feed + counts.
- Use `COUNT(*) FILTER` (Postgres) for multi-status counts in one query.

## API contract

- `dashboardSummarySchema` (denormalized DTO).

## UI

- Skeleton loading state per card; empty state if no data; refreshable via a button.
- Charts use design-token color palette only.

## Validation

- N/A (read-only).

## Testing

- Snapshot the DTO shape; component test with mocked data; E2E that the page renders.

## Observability

- Log query latency; alert if p95 > 300 ms.

## Security

- Permission: `dashboard.read` (implicit for any authenticated user by default).
- Tenant-scoped counts only.
