feat(overview): an activity grid, one cell per history bucket

[Fl0p]

A GitHub-contributions-style Span activity grid leads the Overview, under the KPI row. A line chart answers how much and when; it does not answer what does a week here look like, which is the rhythm question a telemetry front door gets asked most.

The grid

The selected range picks both the lattice and the bucket width it fetches — one bucket, one cell, no client-side re-bucketing:

Range	Grid	Cell	granularity	Window tiled
Year, All	53 × 7, column-major	day	day	371 days
Month	31 × 6, column-major	4 h	4h	31 days
Week	24 × 7, row-major	1 h	hour	7 days
Day	24 × 6, column-major	10 min	10m	24 hours

On Year/All that is the identical request the History block already makes, so SWR serves both from one fetch.

Deviation from the ticket, deliberate: it asked for 27 × 7 on the week grid. 27 hour-columns × 7 rows is 189 hours = 7.875 days — it tiles neither a week nor a day, so no column would be a fixed hour and no row a fixed day, and the grid would drift three hours per row. 24 × 7 is exactly the 7-day window and is the shape 27 × 7 was reaching for. Rationale in the ADR.

API

GET /api/v1/history takes two more bucket widths, granularity=10m and 4h. Additive; no existing caller changes; an unrecognised width still falls back to day rather than 400ing. Like hour, both are answered from spans alone and report the shortfall in covered_since — daily_usage buckets whole UTC days and cannot produce a sub-day bucket. bucket is now documented as a UTC wall-clock label floored to the width.

Two judgement calls worth reviewing

• Absent ≠ empty. The lattice is fixed but the window is rolling, so the leading edge and the rest of today were never queried. Those cells are drawn as an outline with no fill. An empty cell means "we looked and found nothing"; conflating the two is how a heatmap invents a quiet weekend.
• Quartiles, not max-relative. Scaling against the busiest cell was built first and renders a working week as one flat block of full-intensity cells — against a 722-span peak a 200-span day and a 700-span day are both "busy", on a linear ramp and on a log ramp alike. The scale moved to frontend/src/lib/heat.ts; the History page's calendar and hour-of-day heatmaps had a private copy and now read the same five steps.

Verification

• go vet ./... and go test ./... green (golang:1.23-bookworm, CGO on). Four new tests pin the two widths' bucket labels in UTC, the raw-only rule, and the unknown-width fallback.
• npm run build (tsc + vite) green.
• Rendered in Chromium against a seeded instance (35 516 spans / 672 sessions / 120 days) at all five ranges in light and dark: correct cell counts (371/186/168/144 + labels), correct footers, zero console errors.

Follow-up, not in this PR

docs/assets/dashboard-overview.png still shows the pre-grid Overview. The Overview shape is also changing on flo-595-overview-activity-block; one re-shoot after both land beats two conflicting ones.

ADR-0016

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6717da28-d7d0-40ad-8f6f-c9a74b57af8a

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Fl0p]

Squash-merged to main as a43e972 (local squash per the identity rule; both product calls approved — see FLO-596). Branch deleted.