davila7--claude-code-templates/cli-tool/docs_to_claude/ARCHITECTURE.md

Claude Code Templates - Modular Architecture

This document provides detailed technical documentation for the modular architecture implementation of the Claude Code Templates analytics dashboard.

Overview

The analytics dashboard has been refactored from a monolithic architecture to a modern, scalable modular design. This transformation occurred in 4 phases:

1. Phase 1: Backend modularization (Core modules extraction)
2. Phase 2: Frontend modularization (Component-based architecture)
3. Phase 3: WebSocket integration (Real-time communication)
4. Phase 4: Testing & Performance monitoring

Directory Structure

src/
├── analytics.js                          # Main orchestration class
├── analytics/
│   ├── core/                            # Core business logic modules
│   │   ├── StateCalculator.js           # Conversation state detection
│   │   ├── ProcessDetector.js           # Running process detection
│   │   ├── ConversationAnalyzer.js      # Message analysis & parsing
│   │   └── FileWatcher.js               # File system monitoring
│   ├── data/
│   │   └── DataCache.js                 # Multi-level caching system
│   ├── notifications/
│   │   ├── WebSocketServer.js           # WebSocket communication
│   │   └── NotificationManager.js       # Event management
│   └── utils/
│       └── PerformanceMonitor.js        # Performance tracking
├── analytics-web/                       # Frontend modular components
│   ├── index.html                       # Main dashboard page
│   ├── assets/
│   │   ├── css/style.css               # Styling
│   │   └── js/main.js                  # Application entry point
│   ├── components/
│   │   ├── Dashboard.js                # Main dashboard component
│   │   ├── ConversationTable.js        # Conversation display
│   │   └── Charts.js                   # Data visualization
│   └── services/
│       ├── DataService.js              # API communication
│       ├── StateService.js             # State management
│       └── WebSocketService.js         # Real-time communication
└── tests/                               # Comprehensive test suite
    ├── unit/                           # Unit tests for modules
    ├── integration/                    # Integration tests
    └── e2e/                           # End-to-end tests

Backend Architecture

Core Modules

StateCalculator.js

Responsible for determining conversation states based on message analysis and process detection.

Key Features:

• Real-time state detection: active, waiting, idle, completed
• Message pattern analysis for tool usage and errors
• Process-aware state calculation
• Ultra-fast refresh for live updates

API:

const stateCalculator = new StateCalculator();
const state = stateCalculator.determineConversationState(messages, lastModified, runningProcess);
const quickState = stateCalculator.quickStateCalculation(conversation, processes);

ProcessDetector.js

Manages detection and monitoring of running Claude Code processes.

Key Features:

• Cross-platform process detection (macOS, Linux, Windows)
• Process-conversation correlation
• Orphan process identification
• Efficient process monitoring

API:

const detector = new ProcessDetector();
const processes = await detector.getRunningClaudeProcesses();
const enriched = await detector.enrichWithRunningProcesses(conversations, claudeDir, stateCalculator);

ConversationAnalyzer.js

Handles conversation file parsing, analysis, and data extraction.

Key Features:

• JSONL file parsing with error handling
• Token counting and message analysis
• Project detection and categorization
• Integrated caching for performance

API:

const analyzer = new ConversationAnalyzer(claudeDir, dataCache);
const data = await analyzer.loadInitialData(stateCalculator, processDetector);
const conversations = await analyzer.analyzeConversations(files, stateCalculator);

FileWatcher.js

Provides real-time file system monitoring with efficient change detection.

Key Features:

• Chokidar-based file watching
• Intelligent refresh throttling
• Multiple watcher management
• Cache invalidation integration

API:

const watcher = new FileWatcher();
watcher.setupFileWatchers(claudeDir, dataRefreshCallback, processRefreshCallback, dataCache);
watcher.pause(); // Pause monitoring
watcher.resume(); // Resume monitoring

Data Layer

DataCache.js

Multi-level caching system with intelligent invalidation strategies.

Cache Levels:

1. File Content Cache - Raw file content with timestamp validation
2. Parsed Data Cache - Processed conversation data
3. Computation Cache - Expensive calculation results

Key Features:

• TTL-based expiration
• Dependency tracking
• Smart invalidation
• Memory usage optimization
• Performance metrics

API:

const cache = new DataCache();
const content = await cache.getFileContent(filepath);
const parsed = await cache.getParsedData(key, parser);
const result = await cache.getComputationResult(key, computer);
cache.invalidateFile(filepath);

Notification System

WebSocketServer.js

Real-time WebSocket communication with comprehensive client management.

Key Features:

• Client connection management
• Subscription-based messaging
• Heartbeat mechanism
• Message queuing for offline clients
• Performance monitoring integration

API:

const wsServer = new WebSocketServer(httpServer, options, performanceMonitor);
await wsServer.initialize();
wsServer.broadcast(message, channel);
wsServer.notifyConversationStateChange(conversationId, newState, metadata);

NotificationManager.js

Event-driven notification system with subscription management.

Key Features:

• Event subscription management
• WebSocket integration
• Notification queuing
• Client filtering
• Error handling

API:

const manager = new NotificationManager(webSocketServer);
manager.notifyDataRefresh(data, source);
manager.notifyConversationStateChange(id, oldState, newState, metadata);
manager.subscribe(event, callback);

Performance Monitoring

PerformanceMonitor.js

Comprehensive performance tracking and system health monitoring.

Monitoring Capabilities:

• Memory usage tracking
• Request performance metrics
• Cache hit/miss ratios
• WebSocket connection metrics
• Error tracking and alerting
• System health status

Key Features:

• Express middleware integration
• Configurable thresholds
• Metric retention management
• Real-time statistics
• Export capabilities

API:

const monitor = new PerformanceMonitor(options);
monitor.startTimer('operation');
monitor.endTimer('operation', metadata);
monitor.recordRequest(endpoint, duration, statusCode);
const stats = monitor.getStats(timeframe);
const middleware = monitor.createExpressMiddleware();

Frontend Architecture

Component-Based Design

Dashboard.js

Main orchestration component that manages the entire dashboard interface.

Responsibilities:

• Component initialization and lifecycle management
• Service integration (DataService, StateService, WebSocketService)
• Real-time data refresh coordination
• Error handling and recovery
• Performance optimization

Key Features:

• Modular component loading
• Service dependency injection
• Automatic reconnection handling
• Progressive enhancement

ConversationTable.js

Interactive table component for displaying conversation data.

Key Features:

• Real-time status updates
• Interactive sorting and filtering
• Responsive design
• Performance optimization for large datasets
• Export functionality

Charts.js

Data visualization component using Chart.js.

Key Features:

• Multiple chart types support
• Real-time data updates
• Responsive design
• Performance optimization
• Interactive features

Service Layer

StateService.js

Reactive state management with observer pattern implementation.

Key Features:

• Centralized state management
• Subscriber notification system
• State history tracking
• Error state handling
• State persistence

API:

const stateService = new StateService();
stateService.subscribe(callback);
stateService.setState(newState, action);
stateService.updateConversations(conversations);
const conversations = stateService.getConversationsByStatus('active');

DataService.js

API communication layer with intelligent caching and real-time integration.

Key Features:

• HTTP request management
• Response caching with TTL
• WebSocket integration
• Automatic retry logic
• Error handling
• Performance tracking

API:

const dataService = new DataService(webSocketService);
const conversations = await dataService.getConversations();
const states = await dataService.getConversationStates();
const success = await dataService.requestRefresh();

WebSocketService.js

Real-time communication service with automatic reconnection.

Key Features:

• Connection management
• Subscription handling
• Automatic reconnection
• Message queuing
• Heartbeat monitoring
• Error recovery

API:

const wsService = new WebSocketService();
await wsService.connect();
wsService.subscribe('data_updates');
wsService.on('conversation_state_change', handler);
wsService.requestRefresh();

Real-time Communication

WebSocket Protocol

The system uses WebSocket for real-time bidirectional communication between server and clients.

Message Types

Client to Server:

• subscribe - Subscribe to a channel
• unsubscribe - Unsubscribe from a channel
• refresh_request - Request data refresh
• ping - Heartbeat ping

Server to Client:

• connection - Connection established
• data_refresh - Data updated
• conversation_state_change - State changed
• subscription_confirmed - Subscription successful
• pong - Heartbeat response

Channels

• data_updates - General data updates
• conversation_updates - Conversation state changes
• system_updates - System health updates

Fallback Mechanisms

When WebSocket connection is unavailable:

1. Automatic fallback to polling
2. Cache-based updates
3. Manual refresh options
4. Offline mode handling

Performance Optimizations

Caching Strategy

Multi-Level Caching

1. Browser Cache - Static assets and API responses
2. Service Cache - DataService request caching
3. Backend Cache - File content and parsed data
4. Computation Cache - Expensive calculations

Cache Invalidation

• File-based invalidation using modification timestamps
• WebSocket-triggered cache clearing
• TTL-based expiration
• Manual cache control

Memory Management

Backend Optimizations

• Automatic metric cleanup
• Configurable memory thresholds
• Efficient data structures
• Process monitoring

Frontend Optimizations

• Component cleanup on unmount
• Event listener management
• Memory leak prevention
• Performance monitoring

Real-time Efficiency

WebSocket Optimizations

• Connection pooling
• Message compression
• Efficient serialization
• Heartbeat optimization

Update Strategies

• Differential updates
• Batch processing
• Throttling and debouncing
• Smart refresh logic

Testing Framework

Test Categories

Unit Tests

• Individual module testing
• Mock dependencies
• Edge case coverage
• Performance benchmarks

Integration Tests

• End-to-end workflows
• Real data scenarios
• Error condition testing
• Performance testing

Performance Tests

• Load testing
• Memory usage validation
• Response time benchmarks
• Concurrent operation testing

Test Coverage Requirements

• Global Coverage: 70% minimum
• Core Modules: 80% minimum
• Critical Paths: 90% minimum

Testing Tools

• Jest - Test framework
• WebSocket Testing - Real-time communication testing
• Performance Testing - Load and stress testing
• Integration Testing - Complete system validation

Deployment and Operations

Environment Configuration

Development

• Hot reloading
• Debug logging
• Performance profiling
• Test data generation

Production

• Optimized builds
• Error tracking
• Performance monitoring
• Health checks

Monitoring and Alerting

Health Checks

• System resource monitoring
• WebSocket connection health
• Cache performance metrics
• Error rate tracking

Performance Metrics

• Request response times
• Memory usage patterns
• Cache hit ratios
• WebSocket message throughput

Future Enhancements

Planned Features

• Enhanced caching strategies
• Advanced performance analytics
• Multi-user support
• API rate limiting
• Advanced error tracking

Scalability Improvements

• Horizontal scaling support
• Database integration
• Advanced caching layers
• Load balancing

This modular architecture provides a solid foundation for future enhancements while maintaining high performance and reliability.