feat: interactive account map with React Flow canvas

[simple-agent-manager]

Summary

• Adds a full-screen interactive Account Map page (/account-map) that visualizes all entities in a user's account (projects, nodes, workspaces, sessions, tasks) as a node graph using React Flow
• New API endpoint GET /api/account-map aggregates D1 queries + ProjectData DO fan-out with KV caching (30s TTL)
• 6 custom node types with entity-specific styling, animated SVG particle edges, dagre hierarchical layout, search/filter toolbar
• Accessible: aria-pressed on filter chips, prefers-reduced-motion guard on animations, status dot labels, region landmarks
• Nav sidebar updated with Map link between Projects and Settings

Validation

• pnpm lint — 0 errors (warnings only, pre-existing)
• pnpm typecheck — clean
• pnpm test — 9 tests pass (3 API + 6 web)
• Additional validation: specialist review agents (cloudflare, constitution, ui-ux)

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging workflow triggered and passed (run 23746256018)
• Live app verified via Playwright — logged into app.sammy.party using test credentials
• Existing workflows confirmed working — dashboard (project cards), projects (3 listed), settings (all tabs + providers), 0 console errors
• New feature/fix verified on staging — Account Map page loads at /account-map with real data: 3 projects, 15 nodes, 16 workspaces, 85 sessions, 76 tasks; filter chips show counts with aria-pressed; search bar and reorganize button present
• Infrastructure verification completed — N/A: no infra changes
• Mobile and desktop verification notes added for UI changes

Staging Verification Evidence

Screenshot captured of account map on staging showing the full React Flow canvas with entity nodes, filter chips with counts (Projects 3, Nodes 15, Workspaces 16, Sessions 85, Tasks 76), search bar, and reorganize button. Dashboard, projects, and settings pages all load correctly with no console errors.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified — filter chips have 44px min-height touch targets, search clear button expanded, mobile tooltip uses safe-area-inset
• Accessibility checks completed — aria-pressed on filters, prefers-reduced-motion guard, status dot labels, region landmark on canvas
• Shared UI components used or exception documented — uses SAM design tokens throughout
• Playwright visual audit run locally — deferred: staging verification with real data on live app covers the visual scenarios

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. User navigates to /account-map → apps/web/src/pages/AccountMap.tsx
2. useAccountMapData hook calls getAccountMap() → apps/web/src/lib/api.ts:getAccountMap()
3. API request → GET /api/account-map → apps/api/src/routes/account-map.ts handler
4. Handler checks KV cache → fans out 4 D1 queries + ProjectData DO listSessions() per project
5. Response assembled with entities + relationships → cached in KV → returned as JSON
6. Client transforms to React Flow nodes/edges → useAccountMapData.ts applies dagre layout
7. AccountMapCanvas renders <ReactFlow> with custom node types and animated edges
8. useMapFilters manages search/filter state, AccountMapToolbar renders controls

Untested Gaps

Manual staging verification covers the full user flow. Unit tests cover API route behavior (3 tests) and component rendering (6 tests). No automated E2E test for the full browser→API→DO flow; verified manually on staging.

Post-Mortem (Required for bug fix PRs)

N/A: not a bug fix

Exceptions (If any)

• Scope: Playwright visual audit deferred — staging verification with real data on live environment is more comprehensive than local mock-data audits
• Rationale: Real data on staging exercises actual entity counts and layout behavior
• Expiration: N/A

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

• React Flow v12 docs (xyflow.com) for custom node/edge types
• dagre layout library for hierarchical graph positioning

Codebase Impact Analysis

• apps/api/src/routes/account-map.ts — new API route
• apps/api/src/index.ts — route mount + Env type
• apps/web/src/components/account-map/ — new component directory (canvas, toolbar, nodes, edges, hooks, layout, empty state)
• apps/web/src/pages/AccountMap.tsx — new page
• apps/web/src/lib/api.ts — new API function + response type
• apps/web/src/App.tsx — new route
• apps/web/src/components/NavSidebar.tsx — nav item

Documentation & Specs

• apps/api/.env.example updated with new ACCOUNT_MAP_* env vars (ACCOUNT_MAP_MAX_ENTITIES, ACCOUNT_MAP_MAX_SESSIONS_PER_PROJECT, ACCOUNT_MAP_CACHE_TTL_SECONDS)
• CLAUDE.md not updated — new feature does not change existing documented behavior or architecture
• No existing docs reference the Account Map; this is a net-new page with its own API route

Constitution & Risk Check

• Principle XI (No Hardcoded Values): All limits configurable via env vars (ACCOUNT_MAP_MAX_ENTITIES, ACCOUNT_MAP_MAX_SESSIONS_PER_PROJECT, ACCOUNT_MAP_CACHE_TTL_SECONDS)
• Tooltip hide delay extracted as named constant (TOOLTIP_HIDE_DELAY_MS)
• Edge particle count and cycle duration as named constants

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate failed

Failed conditions
2 Security Hotspots

See analysis details on SonarQube Cloud