feat(CHR-25): Chronicle Dashboard Redesign - Complete Implementation

[memyselfandm]

Summary

• Complete implementation of Chronicle Dashboard redesign with real-time monitoring capabilities
• Comprehensive test coverage (90%+) across all components
• Full documentation and hook system improvements

Key Changes

Dashboard Redesign (CHR-25)

• Modern, responsive UI with real-time event streaming
• Virtual scrolling for handling 30+ concurrent sessions
• Performance-optimized components with React Window
• Material Design icons and improved typography
• Dark theme with Chronicle brand colors

Testing Implementation (CHR-6)

• Unit Tests: 90%+ coverage for all components
• Integration Tests: Supabase real-time validation (500 events/sec)
• E2E Tests: Complete user flow testing with Playwright
• Performance Tests: Benchmarking and monitoring suite
• Test utilities and mock infrastructure

Documentation (CHR-5)

• Comprehensive component documentation
• API reference guides
• Architecture documentation
• Developer setup guides

Hook System Fixes (CHR-113)

• Fixed Chronicle hooks to be purely observational
• Removed permission interference
• Improved performance (5s timeout vs 30s)
• Maintained credential obfuscation

Test Results

• Component coverage: 94.5%
• Hook coverage: 96%
• Utilities coverage: 98%
• All tests passing ✅

Related Issues

• CHR-25: Dashboard Redesign
• CHR-6: Testing Implementation
• CHR-5: Documentation
• CHR-113: Hook Performance Fixes
• CHR-84: Component Consolidation

Screenshots

Multiple design iterations and final implementation available in .playwright-mcp/ directory

🤖 Generated with Claude Code

[linear]

CHR-25 Epic: Chronicle Dashboard Redesign

Executive Context

Product: Chronicle - Real-time monitoring system for Claude Code instances
Epic ID: CHR-25
Priority: P1 (Urgent)
Complexity Estimate: Large - Expected 8-12 features, 30-40 tasks

Problem Space

Current Reality: Operators struggle to monitor 3-30 concurrent Claude Code instances effectively. The existing dashboard lacks real-time visibility into session states, particularly sessions awaiting user input. High-frequency events (100-200 events/minute) cause UI performance issues and make it difficult to identify blocking conditions quickly. Current time to identify awaiting sessions averages 15-30 seconds, causing delays in unblocking workflows.

Desired Reality:
A dense, performant monitoring interface that enables operators to identify sessions requiring input within 2 seconds. Real-time event streaming with semantic color coding, batched updates for smooth performance at 200 events/minute, and intelligent sidebar organization that surfaces awaiting sessions immediately. The system should support monitoring 10-30 concurrent sessions from a single view with zero dropped events.

Why This Matters (Business Value):

• User Impact: Reduces operator cognitive load and enables faster response to blocking conditions
• Business Metrics: 85% reduction in mean time to unblock sessions (from 15-30s to <2s)
• Technical Debt: Eliminates performance bottlenecks in high-frequency monitoring and establishes scalable real-time architecture

User Journeys

AI agents use these to generate acceptance criteria and test scenarios

Primary User Journey:

Actor: Operator monitoring 2-30 Claude Code instances
Trigger: New session enters "awaiting input" state
Steps:
1. Operator glances at dashboard → Awaiting Input section highlights new session with yellow accent
2. Operator clicks session in sidebar → Event feed filters to show session history
3. Operator reviews recent events → Understands context and required input
4. Operator switches to Claude Code session → Provides input to unblock
Outcome: Session unblocked within 5 seconds of notification, minimal workflow disruption

Secondary User Journeys:

Actor: Operator during high-activity periods
Trigger: Multiple sessions generating 150-200 events/minute
Steps: Dashboard maintains smooth performance, batched updates prevent UI flooding
Outcome: All events captured, no performance degradation

Actor: Operator after network disruption  
Trigger: WebSocket connection drops and reconnects
Steps: Connection status shows "Reconnecting", events backfill on restore
Outcome: Zero data loss, seamless recovery experience

Edge Cases & Error Flows:

• High session count (30+ sessions): Awaiting Input section caps at 40vh with internal scrolling
• Duplicate session names: System appends last 4 chars of session_id for disambiguation
• Network failures: Exponential backoff reconnection with progress preservation

Success Criteria

These become epic-level acceptance criteria and sprint success metrics

Functional Success:

• Time to identify awaiting session reduces to <2 seconds (p95)
• Zero dropped events at 200 events/minute sustained for 10 minutes
• Sidebar Awaiting Input section auto-populates from all projects
• Event feed maintains chronological order with semantic color coding
• Real-time subscriptions reconnect with complete data backfill

Performance Success:

• Initial dashboard load <2 seconds (p90)
• Event processing latency <100ms (p95) at peak load
• Smooth 60fps scrolling with 100+ visible events
• Memory footprint <100MB during typical workloads

Quality Success:

• 100% uptime for real-time monitoring features
• Successful reconnection in 100% of simulated network interrupts
• Zero UI thrashing during high-frequency event periods

Technical Context

Critical information for AI agents to make correct implementation decisions

System Architecture Touchpoints:

• Frontend: Next.js 15.4.6 with App Router, TypeScript, Tailwind CSS v4
• Backend: Supabase 2.55.0 with PostgreSQL and real-time subscriptions
• Database: sessions and events tables with proper indexing
  • Supabase tables: chronicle_sessions and chronicle_events (to prevent name clashes in public schema)
• Infrastructure:
  • Currently: Local machine deployment
  • Future (potentially): docker container or other hosted/remote deployment
• Integration: Chronicle-installed Claude Code hooks writing to Supabase via Python client

Technical Constraints (MUST follow):

• Must use existing Supabase schema: sessions and events tables cannot be modified
• Must maintain dark theme consistency: Use established color palette from existing dashboard
• Cannot exceed Supabase rate limits: 5 events/sec in production, 10 in development
• Must preserve Chronicle Hooks integration: Events arrive via Python hooks in ~/.claude/hooks/

Technical Preferences (SHOULD follow):

• Prefer Zustand for state management: Replace existing local state with centralized store
• Use Material Design Icons exclusively: Consistent icon system across dashboard
• Implement virtual scrolling for lists: Performance optimization for large datasets
• Apply consistent 24px row height: Dense layout for information throughput

Relevant Code Locations:

Key files/directories AI should examine:
- /apps/dashboard/src/components/ (existing UI components)
- /apps/dashboard/src/hooks/ (useEvents, useSessions, useSupabaseConnection)
- /apps/dashboard/src/lib/ (supabase.ts, eventProcessor.ts, filterUtils.ts)
- /design_variants/ (reference implementations from design sprints)
- /scripts/ (environment validation and health checks)

Feature Decomposition Hints

Guide the AI's epic-breakdown process

Logical Feature Groups:

1. Sidebar Navigation System - Awaiting input monitoring and project organization
   • Likely includes: AwaitingInputSection, ProjectFolder, SessionItem, PresetFilters components
   • Dependencies: Session status determination logic
   • Can parallelize: Yes, independent of other features
2. Header Metrics Display - Real-time dashboard metrics and connection status
   • Likely includes: MetricsDisplay, ThroughputIndicator, ConnectionDot components
   • Dependencies: Real-time subscription health monitoring
   • Can parallelize: Yes, uses separate data streams
3. Event Feed Redesign - High-performance event display with semantic colors
   • Likely includes: EventTableV2, EventRowV2, SubAgentRow, AutoScrollToggle components
   • Dependencies: Event batching and virtual scrolling infrastructure
   • Can parallelize: Yes, uses existing event stream
4. Real-time Data Management - Subscription handling and performance optimization
   • Likely includes: Zustand store, event batching, reconnection logic
   • Dependencies: None (foundational)
   • Can parallelize: No, other features depend on this

Suggested Implementation Order:

1. Foundation (minimal, only if required):
   • Real-time data management with Zustand store
   • Event batching and subscription infrastructure
   • TypeScript type alignment between hooks and dashboard
2. Core Features (maximize parallelization):
   • Sidebar Navigation System - Independent development
   • Header Metrics Display - Independent development
   • Event Feed Redesign - Independent development
3. Integration (minimal):
   • Component integration and layout
   • Performance optimization and testing
   • Documentation updates

Complexity Indicators:

• High Complexity: Real-time subscription management with reconnection logic
• Unknown/Research Needed: Performance impact of virtual scrolling at 200 events/minute scale
• Simple/Straightforward: Component styling and layout using existing design system

Data & State Management

Critical for AI to understand data flow and state changes

Data Model Changes:

New Entities:
  - DashboardStore (Zustand):
      - sessions: Map<string, Session> (required)
      - awaitingSessions: Set<string> (required)
      - selectedSessions: Set<string> (required)
      - events: Event[] (required)
      - connectionStatus: ConnectionStatus (required)
      - eventRate: number (required)

Modified Entities:
  - Event:
      - Add TypeScript types for all Chronicle event types
      - Align with existing database schema
  - Session:
      - Add computed status field (awaiting|active|idle)
      - Add display label formatting

Relationships:
  - Session -> Events (one-to-many via session_id)
  - Project -> Sessions (one-to-many via project_path)

State Management:

• Client State: Dashboard UI state, filters, selections, real-time connection status
• Server State: Sessions and events from Supabase with SWR caching and revalidation
• Cache Strategy: SWR for session data (5min TTL), real-time subscriptions for events
• Real-time Updates: Supabase WebSocket subscriptions with 100ms batching window

Integration Points

How this epic connects with existing systems

Internal Integrations:

• Chronicle Hooks System: Python hooks capture Claude Code events and write to Supabase
• Existing Dashboard Components: Reuse ConnectionStatus, ErrorBoundary, and UI primitives
• Supabase Client: Leverage existing connection management and environment validation

External Integrations:

• Supabase Real-time: WebSocket subscriptions for INSERT events on events table
• Vercel Analytics: Optional usage tracking for performance monitoring
• Sentry Error Tracking: Optional error reporting and performance monitoring

API Contract Changes:

Database Queries (Enhanced):
  - GET sessions with last_event: Include event metadata for status determination
  - GET events with filtering: Support session_id and event_type filters
  - SUBSCRIBE events: Real-time INSERT events with batching

Type Definitions (New):
  - EventType: session_start, user_prompt_submit, pre_tool_use, post_tool_use, notification, stop, subagent_stop, error
  - ConnectionStatus: connected, reconnecting, disconnected
  - PresetFilter: All, Active, Awaiting, Errors, Recent

Testing Strategy

Guides AI agents in writing appropriate tests

Unit Testing Focus:

• Session status determination logic (awaiting vs active vs idle)
• Event batching and deduplication algorithms
• Filter state management and session selection
• Connection status handling and reconnection logic

Integration Testing Focus:

• Real-time subscription handling with mock WebSocket
• Component interaction between sidebar selection and event feed filtering
• Performance under simulated high-frequency event loads

E2E Testing Scenarios:

1. Primary Happy Path: Load dashboard → see awaiting sessions → click session → view filtered events
2. High Load Performance: Sustain 200 events/minute for 10 minutes without performance degradation
3. Network Recovery: Simulate connection drop → verify reconnection → validate data backfill

Non-Functional Requirements

Constraints that affect implementation choices

Performance:

• Response Time: <2 seconds for initial load (p90), <100ms for event processing (p95)
• Throughput: Support 200 events/minute sustained, 300 events/minute peak
• Resource Usage: <100MB memory footprint, <5% CPU during normal operation

Security:

• Authentication: Use Supabase Auth (future), currently open access
• Authorization: No session-level permissions in MVP
• Data Protection: No PII in event metadata, obfuscate session IDs in UI

Scalability:

• Expected Load: 3-30 concurrent sessions per operator
• Growth Projection: Support up to 50 sessions within 6 months
• Bottleneck Risks: WebSocket connection limits, browser memory with large event arrays

Accessibility:

• WCAG Level: AA compliance for color contrast in dark theme
• Specific Requirements: Keyboard navigation (j/k, 1/2/3, /), screen reader support for status changes

Documentation & Knowledge

Ensures AI agents create appropriate documentation

Documentation to Create/Update:

• Component architecture guide for sidebar, header, and event feed
• Real-time subscription patterns and best practices
• Performance optimization techniques for high-frequency updates
• Event type definitions and semantic color mappings
• Troubleshooting guide for connection issues

Knowledge Transfer Needs:

• Key Decisions: Zustand over Redux for simpler state management, virtual scrolling for performance
• Patterns Established: Event batching pattern, semantic color system, session status determination
• Lessons Learned: Supabase rate limiting considerations, WebSocket reconnection handling

Rollout & Monitoring

Helps AI agents build in observability

Feature Flags:

• dashboard_v2_enabled: Controls new dashboard vs legacy (Default: Disabled)
• virtual_scrolling_enabled: Performance feature toggle (Default: Enabled)
• event_batching_enabled: Batching optimization toggle (Default: Enabled)

Metrics to Track (Future):

• Business Metrics: Time to identify awaiting sessions, operator sessions monitored per hour
• Technical Metrics: Event processing latency, WebSocket connection uptime, memory usage
• User Metrics: Dashboard load time, filter usage frequency, sidebar interaction patterns

Alerts to Configure (Future):

• Event processing latency >200ms: Alert to investigate performance issues
• WebSocket disconnection >30s: Alert for infrastructure problems
• Memory usage >150MB: Alert for memory leaks

Context & References

Additional context for AI agents

Related Work:

• CHR-24 (Chronicle system foundation)
• Design Sprints: GitHub branch ch-design-sprints contains variant explorations in /design_variants/ directory
• Guidance from design sprints:

consolidated_guidance.md

Technical Debt Addressed:

• Performance bottlenecks: High-frequency event rendering causing UI lag
• State management complexity: Multiple local state patterns inconsistent across components
• Type safety gaps: Missing TypeScript definitions for Chronicle event types

Future Considerations:

• Phase 2: Comprehensive filtering and search functionality
• Phase 3: Tool lifecycle grouping and timeline visualization

---

AI Agent Guidance

Explicit instructions for the epic-breakdown command

Parallelization Hints

Definitely Parallel:

• Sidebar Navigation System (independent component tree)
• Header Metrics Display (separate data streams)
• Event Feed Redesign (existing event infrastructure)

Possibly Parallel:

• UI Components after data management foundation is ready
• Integration testing after individual components complete

Definitely Sequential:

• Real-time Data Management MUST complete first (all features depend on Zustand store)
• Integration and performance optimization MUST be last (requires all components)

Expected Output Scale

• Features: ~8-10 features expected (sidebar, header, event feed, data management, testing, docs)
• Tasks per Feature: ~3-5 tasks per feature (component implementation, styling, integration, testing)
• Total Issues: ~35-45 issues total

Special Considerations

• Reference Implementation Reuse: Leverage existing design variants in /design_variants/ folder on the branch ch-design-sprints for styling and structure
• Performance-First Development: Implement virtual scrolling and batching from start, not as optimization
• Type Safety Priority: Ensure complete TypeScript coverage for all Chronicle event types and state

---

Quick Checklist for Human Review

Before passing to AI for breakdown:

• Problem and solution are clear
• User journeys cover main use cases
• Success criteria are measurable
• Technical constraints are explicit
• Dependencies are identified
• Parallelization opportunities noted
• Edge cases are documented
• Integration points are specified
• Testing strategy is clear
• Documentation needs are listed

---

Template Version: 1.0 - Optimized for AI-First Development with Linear
Chronicle Dashboard Redesign - Epic CHR-25