Epic: Token Usage Analytics v1 on Cloudflare Workers

[newbish]

Outcome

Ship an internal operator-facing analytics app that shows daily token usage, cost, latency, model mix, tool mix, and anomaly issues on Cloudflare Workers using D1-backed rollups.

Why this matters

Teams need daily visibility into AI usage without digging through logs, provider exports, or one-off spreadsheets.

Scope

• TanStack Start app deployed on Cloudflare Workers
• D1/Drizzle-backed rollup model
• Dense dashboard for overview, models, and tools
• Ingestion path for source usage data
• Query path optimized for daily aggregates
• Issue/anomaly surfacing for cost and reliability signals

Execution order

1. Foundation and deployment wiring
2. Ingestion contract
3. Daily rollup materialization
4. Live dashboard queries
5. Drilldowns and persistent filters
6. Issue detection and guardrails
7. Auth and workspace scoping, if needed
8. Hardening and polish

Definition of done

• Dashboard runs on Workers
• D1 schema and migrations are in repo
• Live data replaces mock overview data
• Team can trust day-level numbers for cost and usage decisions

[newbish]

Execution checklist for this epic:

• Slice 1: Foundation and deployment wiring #2 Slice 1: Foundation and deployment wiring
• Slice 2: Define ingestion contract and import path #3 Slice 2: Define ingestion contract and import path
• Slice 3: Materialize daily rollups and backfill logic #4 Slice 3: Materialize daily rollups and backfill logic
• Slice 4: Replace mock dashboard data with live D1 queries #5 Slice 4: Replace mock dashboard data with live D1 queries
• Slice 5: Add drilldowns, detail routes, and persistent filters #6 Slice 5: Add drilldowns, detail routes, and persistent filters
• Slice 6: Detect anomalies and populate the issue feed #7 Slice 6: Detect anomalies and populate the issue feed
• Slice 7: Add internal auth and workspace scoping if distribution expands #8 Slice 7: Add internal auth and workspace scoping if distribution expands
• Slice 8: Seed data, CI, smoke tests, and operational hardening #9 Slice 8: Seed data, CI, smoke tests, and operational hardening
• Bootstrap Cloudflare D1 database and production deployment config #10 Bootstrap Cloudflare D1 database and production deployment config

[newbish]

Epic note: mobile responsiveness is now an explicit quality bar for the dashboard, not post-launch garnish. PR #14 includes a breakpoint pass so the current overview layout degrades more cleanly on phones and smaller tablets. Future slices should preserve that behavior as detail routes and filters expand the surface area.