cyclone/docs/superpowers/specs/2026-07-02-cyclone-dashboard-recent-batches-design.md

SP30 — Dashboard "Recent batches" widget: glance how the last few billed

Status: Approved, 2026-07-02. Branch: sp30-recent-batches-widget Spec → plan → implement → atomic merge into main.

Goal

The Dashboard already shows six-month KPIs (billed, denial rate, etc.) but the operator has no way to see how the last few batches actually billed without clicking through to /batches. Add a single Dashboard card that lists the 5 most recently parsed batches with one-line outcome per batch — so the operator can spot a batch that landed entirely rejected (or has a sudden spike in rejections) at a glance, the moment they log in.

Scope

Backend — 1 file modified (backend/src/cyclone/api.py)

list_batches handler (api.py:1769-1808):

• Extend each returned item with billing-outcome fields, computed via a single batched SQL query per request (no N+1):
  • acceptedCount (int)
  • rejectedCount (int)
  • pendingCount (int)
  • billedTotal (float)
  • topRejectionReason (string|null, truncated to 60 chars)
  • hasProblem (bool — true when rejectedCount > 0 or any 277CA A4/A6/A7 claim on the batch)
• New helper _batch_summary_billing_outcomes(records) runs one GROUP BY query and one rejection-reason probe. Mirrors the existing _batch_summary_claim_count / _batch_summary_claim_ids helpers (api.py:1740-1764).

Backend — 1 test file extended (backend/tests/test_api_gets.py)

+2 tests after the existing test_batches_* block at lines 47-101:

• test_batches_includes_billing_outcome — seed one batch with 3 claims (1 paid $100, 1 rejected $50 reason="999 AK5 R", 1 submitted $75); GET /api/batches; assert acceptedCount=1, rejectedCount=1, pendingCount=1, billedTotal=225.0, topRejectionReason="999 AK5 R", hasProblem=True.
• test_batches_835_kind_returns_zero_billed_and_no_rejection — seed one 835 batch; assert acceptedCount=0, rejectedCount=0, billedTotal=0, topRejectionReason=null, hasProblem=False.

Reuses the seeded_store fixture (line 27) and the direct ORM-insert pattern from test_dashboard_kpis.py:36-91.

Frontend — 1 type extension + 1 new component + 1 layout wire-up

src/lib/api.ts:245-259 — extend BatchSummary with 6 optional fields:

acceptedCount?, rejectedCount?, pendingCount?,
billedTotal?, topRejectionReason?, hasProblem?

Optional preserves backward compat with existing tests in Upload.history.test.tsx, Batches.test.tsx, BatchDiff.test.tsx.

src/components/RecentBatchesWidget.tsx (NEW, ~120 LOC):

• Card chrome mirroring the Dashboard "Recent activity" Card.
• Header: <Layers /> icon + "Recent batches" title + counter chip "{N} latest".
• Empty state: "No batches yet." (matches ActivityFeed).
• Row markup: status icon (CheckCircle2 / AlertTriangle) + filename + (kind · time · top rejection reason) + billed/accepted breakdown (or "N payments" for 835).
• Click → onRowClick(id); Enter key → same. Mirrors Dashboard.tsx:300-307.

src/pages/Dashboard.tsx — insert the widget as a full-width row BETWEEN the KPI tile row (line 245) and the "Activity + Top providers" grid (line 247):

• const recentBatchesQuery = useBatches(5); — queryKey ["batches", 5] (distinct from ["batches", null] used by Upload).
• animationDelay: ${sectionBase + 200}ms so it lands after the KPI stagger and before the Activity row.
• onRowClick → navigate('/batches?batch=' + id).

Frontend — 1 test file added + 1 extended

src/components/RecentBatchesWidget.test.tsx (NEW, 3 tests):

• empty state
• 2-batch render (one clean, one with rejections) — verifies icon tint, billed total, accepted count, click + Enter key handler
• 835 row renders "N payments" not $

src/pages/Dashboard.test.tsx (+1 test):

• widget renders, row click navigates to /batches?batch=ID.

Decisions

• D1 — widget shows 5 batches, not "today only" or "last 24h". 5 is the natural at-a-glance cap. Hard-coded constant RECENT_BATCHES_LIMIT = 5 in the page.
• D2 — backend returns billing outcome on EVERY /api/batches row, not a separate /api/batches/summary endpoint. The query cost is bounded by the existing limit and is one extra GROUP BY — no N+1. Returning on the list endpoint means future surfaces (Batches page, Upload History) can use the same fields without another endpoint.
• D3 — hasProblem drives the visible status, not rejectedCount > 0 directly. 277CA A4/A6/A7 payer-rejected claims also count as problems. Mirrors the Inbox rejected + payer_rejected aggregation.
• D4 — 835 (ERA) rows show "N payments" instead of a $ figure. The Remittance table has no batch-level total_charge aggregate; payments count is the honest, glanceable signal.
• D5 — full-width row above the Activity grid, not a 2/3 + 1/3 split. The widget is the operator's primary "how's it going?" affordance; full width reads as the headline.

Out of scope (deferred)

• Trend sparkline per batch (last N parse throughput).
• Click-to-filter the widget itself by status.
• Live-tail batch_parsed event wiring (no such event exists yet).
• A "missing-ack-alarm" surfacing on claims SUBMITTED >24h with zero 999 acks (separate UX concern).

Tech Stack

Python 3.11+, FastAPI, SQLAlchemy 2.x, SQLite (encrypted via SQLCipher), React 18 + TypeScript + Vite, TanStack Query, lucide-react. Same as SP29.

File footprint

Estimated 7 files changed, ~270 LOC.

• Backend modified (1): backend/src/cyclone/api.py (+~60 LOC).
• Backend test extended (1): backend/tests/test_api_gets.py (+~70 LOC).
• Frontend type extended (1): src/lib/api.ts (+~8 LOC).
• Frontend component added (1): src/components/RecentBatchesWidget.tsx (NEW, ~120 LOC).
• Frontend layout wire-up (1): src/pages/Dashboard.tsx (+~20 LOC).
• Frontend test added (1): src/components/RecentBatchesWidget.test.tsx (NEW, ~150 LOC).
• Frontend test extended (1): src/pages/Dashboard.test.tsx (+~40 LOC).

Risks

• Aggregate query cost on /api/batches — bounded by the existing limit (default 100, capped at 1000); one GROUP BY ≤60k rows is sub-50ms on SQLite.
• Backwards compat of BatchSummary — new fields are optional, so every existing test that constructs BatchSummary continues to pass.
• topRejectionReason truncation — capped at 60 chars in the backend; tested with one assertion on a long reason.
• Dashboard layout choreography — widget uses animationDelay: sectionBase + 200ms; tested visually in the Playwright smoke test.