agent-ecosystem/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-02-12

Pattern Overview

Overall: Three-process Electron architecture with domain-driven service layer and unidirectional data flow

Key Characteristics:

• Electron main process (Node.js) handles file system access, JSONL parsing, and business logic via domain-organized services
• Renderer process (React) manages UI state through Zustand slices with per-tab isolation
• Preload script provides secure IPC bridge via contextBridge
• Data flows: JSONL files → Services (parse/analyze) → IPC → Zustand store → React components
• Service layer organized into 5 domains: analysis, discovery, error, infrastructure, parsing

Layers

Main Process (Node.js):

• Purpose: File system access, session parsing, chunk building, business logic
• Location: src/main/
• Contains: Entry point (index.ts), services (domain-organized), IPC handlers, types, utilities
• Depends on: Electron APIs, Node.js file system, shared types
• Used by: Renderer process via IPC

Preload Bridge:

• Purpose: Secure IPC communication layer between main and renderer
• Location: src/preload/
• Contains: ElectronAPI implementation (index.ts), IPC channel constants
• Depends on: Electron contextBridge, IPC channel definitions
• Used by: Renderer process via window.electronAPI

Renderer Process (React):

• Purpose: UI rendering, state management, user interaction
• Location: src/renderer/
• Contains: React components, Zustand store, hooks, utilities, contexts
• Depends on: React, Zustand, ElectronAPI, shared types
• Used by: End user

Shared Code:

• Purpose: Cross-process types, pure utilities, constants
• Location: src/shared/
• Contains: Type definitions, token formatting, model parsing, logger
• Depends on: Nothing (pure TypeScript)
• Used by: Main, renderer, preload processes

Service Domains (Main Process):

• Purpose: Business logic organized by responsibility
• Location: src/main/services/{domain}/
• Contains: 5 domains with specialized services
• Depends on: Node.js APIs, shared types, utilities
• Used by: IPC handlers, main process lifecycle

Data Flow

Session Loading Flow:

1. User selects project/session in sidebar (renderer)
2. Renderer calls window.electronAPI.getSessionDetail(projectId, sessionId)
3. IPC handler in src/main/ipc/sessions.ts receives request
4. Handler checks DataCache (LRU cache, 50 entries, 10min TTL)
5. On cache miss: SessionParser reads JSONL file from ~/.claude/projects/{encoded-path}/{sessionId}.jsonl
6. SessionParser parses messages, extracts metadata, calculates metrics
7. SubagentResolver finds subagent files in {sessionId}/subagents/, parses them, links to Task calls
8. ChunkBuilder orchestrates chunk building: classifies messages (user/AI/system/noise), groups into chunks, attaches subagents
9. Result cached in DataCache and returned via IPC
10. Renderer receives data, updates Zustand store (sessionDetailSlice)
11. React components re-render with new data

Real-time Update Flow:

1. FileWatcher detects change in session JSONL file (100ms debounce)
2. FileWatcher emits 'file-change' event with { type, path, projectId, sessionId, isSubagent }
3. Main process forwards event to renderer via mainWindow.webContents.send('file-change', event)
4. Renderer's initializeNotificationListeners() receives event
5. Store action refreshSessionInPlace() called (debounced 150ms)
6. Cache invalidated, session re-parsed
7. Store updated without changing selectedSessionId (no flicker)
8. Components re-render with updated data

State Management:

• Zustand store with 14 slices (project, session, sessionDetail, subagent, conversation, tab, tabUI, pane, ui, notification, config, repository, connection, update)
• Each slice follows pattern: { data, selectedId, loading, error }
• Per-tab UI state isolated in tabUISlice using tabId as key
• IPC event listeners registered once in App.tsx, update store directly

Key Abstractions

Chunk (Visualization Unit):

• Purpose: Independent timeline visualization unit for chat display
• Examples: UserChunk, AIChunk, SystemChunk, CompactChunk
• Pattern: Discriminated union on type field, each with timestamp, duration, metrics (tokens, cost, tools)
• Built by: ChunkBuilder orchestrating ChunkFactory, MessageClassifier, ProcessLinker

Process (Subagent):

• Purpose: Represents spawned subagent execution with timing and metrics
• Examples: Task tool subagents, teammate messages in team coordination
• Pattern: Contains id, name, startTime, endTime, metrics, isParallel, optional team metadata
• Built by: SubagentResolver parsing subagent JSONL files, linking to Task calls, detecting parallel execution

Service (Business Logic):

• Purpose: Domain-specific business logic with single responsibility
• Examples: ChunkBuilder (analysis), ProjectScanner (discovery), SessionParser (parsing), NotificationManager (infrastructure), ErrorDetector (error)
• Pattern: Class-based, injected dependencies via constructor, exported from domain barrel
• Location: src/main/services/{domain}/

Zustand Slice (State Domain):

• Purpose: Domain-specific state management with actions
• Examples: sessionSlice, tabSlice, notificationSlice
• Pattern: Factory function returning slice with data, actions, selectors
• Combined in: src/renderer/store/index.ts via create<AppState>()

IPC Handler (Communication):

• Purpose: Request/response handlers for renderer-to-main communication
• Examples: get-projects, get-session-detail, notifications:get
• Pattern: Domain-organized modules with initialize/register/remove functions
• Location: src/main/ipc/{domain}.ts

Entry Points

Main Process Entry:

• Location: src/main/index.ts (381 lines)
• Triggers: app.whenReady() Electron event
• Responsibilities: Initialize services (ProjectScanner, SessionParser, SubagentResolver, ChunkBuilder, DataCache, FileWatcher, NotificationManager, UpdaterService, SshConnectionManager), register IPC handlers, create BrowserWindow, start file watcher, apply configuration

Renderer Entry:

• Location: src/renderer/main.tsx (12 lines)
• Triggers: Page load after Electron window created
• Responsibilities: Render React app (<App />), mount to #root div

Preload Entry:

• Location: src/preload/index.ts (369 lines)
• Triggers: Before renderer loads (Electron lifecycle)
• Responsibilities: Expose ElectronAPI via contextBridge, wrap IPC calls with type-safe interface, provide event listener setup/cleanup

React App Component:

• Location: src/renderer/App.tsx
• Triggers: React render
• Responsibilities: Initialize theme, dismiss splash screen, register IPC event listeners (initializeNotificationListeners()), render layout (<TabbedLayout />)

Error Handling

Strategy: Layer-specific error boundaries with graceful degradation

Patterns:

• Main process: Try/catch in services and IPC handlers, log errors with createLogger(), return null or empty arrays on failure
• Renderer: React <ErrorBoundary> component catches render errors, shows fallback UI
• IPC: Config handlers return { success: boolean, data?, error? } wrapper, other handlers return null on failure
• Store actions: Catch async errors, set error state, display in UI

Cross-Cutting Concerns

Logging: createLogger(namespace) from @shared/utils/logger, used throughout main and renderer

Validation:

• Path validation in src/main/ipc/validation.ts via validatePath(), validateMentions()
• Config validation in src/main/ipc/configValidation.ts for user input sanitization
• Type guards in src/main/ipc/guards.ts for IPC argument validation

Authentication: Not applicable (local desktop app accessing user's file system)

Caching:

• DataCache service (LRU, 50 entries, 10min TTL) for parsed session data
• Cache invalidation on file changes detected by FileWatcher
• Automatic cleanup every 5 minutes

Performance:

• Virtual scrolling for session lists and message lists (@tanstack/react-virtual)
• Debounced file watching (100ms) to batch rapid changes
• Session refresh debouncing (150ms) to prevent redundant IPC calls
• LRU cache to avoid re-parsing large JSONL files

Configuration:

• ConfigManager service manages ~/.claude-devtools/config.json
• Accessed via configManager.getConfig(), configManager.updateConfig()
• IPC handlers in src/main/ipc/config.ts for renderer access
• Settings UI in src/renderer/components/settings/

---

Architecture analysis: 2026-02-12