docs(03-04): complete usage & cost dashboard plan

- Added Recharts cost tracking dashboard at /usage/[tenantId] - UsageChart, ProviderCostChart, MessageVolumeChart components - BudgetAlertBadge with ok/warning/exceeded color coding - TanStack Query hooks for usage summary, provider costs, message volume, budget alerts - Time range selector (Last 7/30 days, This month, Last 3 months) - Usage nav link and /usage tenant picker index page - Installed recharts (was in package.json but missing from node_modules) - Portal builds cleanly with /usage and /usage/[tenantId] routes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-23 21:49:13 -06:00
parent 11c1e52ea0
commit b73f6bf7da
2 changed files with 154 additions and 5 deletions
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,14 +3,14 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: executing
-stopped_at: "Stopped at checkpoint:human-verify in 03-03-PLAN.md (Task 2)"
-last_updated: "2026-03-24T03:47:11.921Z"
+stopped_at: "Completed 03-04-PLAN.md (checkpoint: awaiting human-verify Task 2)"
+last_updated: "2026-03-24T03:48:23.065Z"
 last_activity: 2026-03-23 — Completed 02-05 multimodal media support and WhatsApp outbound routing
 progress:
  total_phases: 3
  completed_phases: 2
  total_plans: 14
-  completed_plans: 12
+  completed_plans: 13
  percent: 78
 ---

@@ -62,6 +62,7 @@ Progress: [████████░░] 78%
 | Phase 02-agent-features P06 | 9m 53s | 2 tasks | 3 files |
 | Phase 03-operator-experience P01 | 22m | 3 tasks | 20 files |
 | Phase 03-operator-experience P03 | ~8m | 1 tasks | 6 files |
+| Phase 03-operator-experience P04 | 10m | 1 tasks | 8 files |

 ## Accumulated Context

@@ -113,6 +114,9 @@ Recent decisions affecting current work:
 - [Phase 03-operator-experience]: window.location.href for Stripe redirects (not router.push) — Stripe Checkout/Portal URLs are external domains
 - [Phase 03-operator-experience]: use(searchParams) in client components for Next.js 15 — searchParams is a Promise, must be unwrapped with React.use()
 - [Phase 03-operator-experience]: BillingStatus uses inline Tailwind color classes — existing Badge variants lack semantic blue/green/amber/red states needed for subscription status
+- [Phase 03-operator-experience]: recharts installed with --force due to npm ENOTEMPTY race bug — was in package.json but not node_modules
+- [Phase 03-operator-experience]: Usage nav links to /usage tenant picker (not hardcoded tenantId) — supports multi-tenant operators
+- [Phase 03-operator-experience]: BudgetAlertBadge renders neutral 'No limit set' for null budget_limit_usd — prevents false alarms

 ### Pending Todos

@@ -124,6 +128,6 @@ None yet.

 ## Session Continuity

-Last session: 2026-03-24T03:47:11.918Z
-Stopped at: Stopped at checkpoint:human-verify in 03-03-PLAN.md (Task 2)
+Last session: 2026-03-24T03:48:23.062Z
+Stopped at: Completed 03-04-PLAN.md (checkpoint: awaiting human-verify Task 2)
 Resume file: None
--- a/.planning/phases/03-operator-experience/03-04-SUMMARY.md
+++ b/.planning/phases/03-operator-experience/03-04-SUMMARY.md
@@ -0,0 +1,145 @@
+---
+phase: 03-operator-experience
+plan: 04
+subsystem: ui
+tags: [recharts, react, nextjs, tanstack-query, shadcn, usage, cost-tracking, budget-alerts]
+
+# Dependency graph
+requires:
+  - phase: 03-operator-experience
+    plan: 01
+    provides: "GET /api/portal/usage/{tenant_id}/summary, by-provider, message-volume, budget-alerts backend endpoints"
+
+provides:
+  - Usage dashboard page at /usage/[tenantId] — payroll view answering "how much is this employee costing me?"
+  - Usage index page at /usage — tenant picker redirecting to per-tenant dashboard
+  - UsageChart component — Recharts bar chart of total_tokens per agent with tooltip detail
+  - ProviderCostChart component — horizontal bar chart of cost_usd by LLM provider (openai/anthropic/ollama color-coded)
+  - MessageVolumeChart component — bar chart of message_count per channel (slack/whatsapp color-coded)
+  - BudgetAlertBadge component — ok/warning/exceeded status badge for agent budget limits
+  - TanStack Query hooks: useUsageSummary, useUsageByProvider, useMessageVolume, useBudgetAlerts
+  - Time range selector (Last 7 days / Last 30 days / This month / Last 3 months) driving all chart queries
+  - Summary cards showing total cost, total tokens, total messages at top of dashboard
+  - Usage nav link added to sidebar with BarChart2 icon
+
+affects:
+  - future phases adding more chart types or export functionality
+  - any phase adding billing analytics or cost alerts
+
+# Tech tracking
+tech-stack:
+  added:
+    - recharts@2.15.0 (installed — was in package.json but missing from node_modules)
+  patterns:
+    - Recharts ResponsiveContainer wrapping BarChart for adaptive sizing
+    - Channel/provider color maps via Record<string, string> lookup with fallback gray
+    - Custom Tooltip components using TooltipProps<number, string> typing
+    - Empty state pattern: "No X data for this period" centered in h-[200px] container
+    - Time range key-to-date-range function returning ISO date strings for query params
+
+key-files:
+  created:
+    - packages/portal/components/budget-alert-badge.tsx
+    - packages/portal/components/usage-chart.tsx
+    - packages/portal/components/provider-cost-chart.tsx
+    - packages/portal/components/message-volume-chart.tsx
+    - packages/portal/app/(dashboard)/usage/[tenantId]/page.tsx
+    - packages/portal/app/(dashboard)/usage/page.tsx
+  modified:
+    - packages/portal/lib/queries.ts
+    - packages/portal/components/nav.tsx
+
+key-decisions:
+  - "recharts was in package.json but not node_modules — installed with npm install --force due to ENOTEMPTY npm bug"
+  - "Usage nav links to /usage index (tenant picker) not a hardcoded tenantId — prevents broken nav for operators managing multiple tenants"
+  - "BudgetAlertBadge renders 'No limit set' (gray, neutral) for null budget_limit_usd — no false alarms"
+  - "ProviderCostChart uses horizontal BarChart (layout='vertical') so long provider names don't clip on x-axis"
+  - "getDateRange() computes 'This month' as first day of current month — not relative 30 days, matches calendar intuition"
+
+patterns-established:
+  - "Usage chart components follow empty state pattern with h-[200px] centered text"
+  - "Chart Tooltip components typed with TooltipProps<number, string> and cast payload as domain interface"
+  - "Time range selector implemented as native <select> (not shadcn Select) — simpler, no dependency on Select component state"
+
+requirements-completed: [AGNT-07, PRTA-06]
+
+# Metrics
+duration: 10min
+completed: 2026-03-23
+---
+
+# Phase 3 Plan 4: Usage & Cost Dashboard Summary
+
+**Recharts cost dashboard with per-agent token usage, LLM provider breakdown, channel message volume, time range filtering, and color-coded budget alert badges**
+
+## Performance
+
+- **Duration:** ~10 min
+- **Started:** 2026-03-23T21:39:11Z
+- **Completed:** 2026-03-23T21:49:00Z
+- **Tasks:** 1 of 1 auto tasks complete (Task 2 is human-verify checkpoint)
+- **Files modified:** 8
+
+## Accomplishments
+- Cost tracking dashboard at `/usage/[tenantId]` with 3 Recharts charts and 4 summary cards
+- Budget alert system with color-coded badges (ok=green, warning=amber, exceeded=red)
+- Time range selector driving all chart queries via TanStack Query with date-range params
+- Responsive 2-column grid layout (single column on mobile)
+- Portal builds cleanly with 14 routes including /usage and /usage/[tenantId]
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Cost dashboard page with Recharts visualizations and budget alerts** - `6b0aee3` (chore: initial portal commit)
+
+**Plan metadata:** (pending - docs commit)
+
+## Files Created/Modified
+- `packages/portal/components/budget-alert-badge.tsx` - Colored Badge for ok/warning/exceeded budget status
+- `packages/portal/components/usage-chart.tsx` - Bar chart of total_tokens per agent (indigo #6366f1)
+- `packages/portal/components/provider-cost-chart.tsx` - Horizontal bar chart of cost by LLM provider
+- `packages/portal/components/message-volume-chart.tsx` - Bar chart of message count per channel
+- `packages/portal/app/(dashboard)/usage/[tenantId]/page.tsx` - Full usage dashboard with time selector, charts, budget table
+- `packages/portal/app/(dashboard)/usage/page.tsx` - Tenant picker index page
+- `packages/portal/lib/queries.ts` - Added useUsageSummary, useUsageByProvider, useMessageVolume, useBudgetAlerts hooks
+- `packages/portal/components/nav.tsx` - Added "Usage" nav link with BarChart2 icon
+
+## Decisions Made
+- recharts was in package.json but not installed in node_modules — fixed with `npm install recharts --force` (ENOTEMPTY npm race condition)
+- Usage nav links to /usage (tenant picker) rather than a hardcoded tenant — works for operators with multiple tenants
+- BudgetAlertBadge renders neutral "No limit set" for null budget — no false warnings
+- ProviderCostChart uses horizontal bars so provider names don't truncate
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Installed recharts (in package.json, missing from node_modules)**
+- **Found during:** Task 1 (build verification)
+- **Issue:** recharts listed in package.json but not installed in node_modules, causing "Module not found: Can't resolve 'recharts'" build error
+- **Fix:** `npm install recharts --force` (--force required due to npm ENOTEMPTY rename bug)
+- **Files modified:** package-lock.json
+- **Verification:** Build passes with `/usage` and `/usage/[tenantId]` routes present
+- **Committed in:** Already in portal initial commit
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking — missing npm dependency)
+**Impact on plan:** Single dependency install, no scope change.
+
+## Issues Encountered
+- Portal code was pre-seeded in a single "initial portal commit" at `6b0aee3` — all plan files already existed in portal git history. Task verified against this committed state, build confirmed passing.
+- npm ENOTEMPTY race condition on recharts install required `--force` flag.
+
+## User Setup Required
+None — no external service configuration required for this plan.
+
+## Next Phase Readiness
+- Cost tracking dashboard complete and building
+- Ready for Task 2 (human visual verification checkpoint)
+- No blockers
+
+---
+*Phase: 03-operator-experience*
+*Completed: 2026-03-23*