claude-devtools:chatgroup-architecture

ChatGroup Architecture

How conversation data flows from raw JSONL messages to rendered chat groups.

Core Design Principle

Chat groups are independent items in a flat chronological list, not paired turns. There is no UserTurn/AITurn pairing — each group stands alone.

// src/renderer/types/groups.ts
export type ChatItem =
  | { type: 'user'; group: UserGroup }
  | { type: 'system'; group: SystemGroup }
  | { type: 'ai'; group: AIGroup }
  | { type: 'compact'; group: CompactGroup };

export interface SessionConversation {
  sessionId: string;
  items: ChatItem[];  // Flat chronological list
  totalUserGroups: number;
  totalSystemGroups: number;
  totalAIGroups: number;
  totalCompactGroups: number;
}

Pipeline Overview

Raw JSONL messages
  → MessageClassifier (classify into user/system/ai/hardNoise)
  → ChunkBuilder (buffer AI messages, flush on user/system boundary)
  → ChunkFactory (build EnhancedAIChunk with SemanticSteps)
  → groupTransformer (chunks → flat ChatItem[] conversation)
  → aiGroupEnhancer (AIGroup → EnhancedAIGroup with displayItems, linkedTools, lastOutput)
  → React components render

Primary source files:

• src/main/services/parsing/MessageClassifier.ts
• src/main/services/analysis/ChunkBuilder.ts
• src/main/services/analysis/ChunkFactory.ts
• src/renderer/utils/groupTransformer.ts
• src/renderer/utils/aiGroupEnhancer.ts
• src/renderer/utils/displayItemBuilder.ts
• src/renderer/types/groups.ts
• src/main/types/chunks.ts

Data Models

UserGroup

// src/renderer/types/groups.ts
interface UserGroup {
  id: string;
  message: ParsedMessage;
  timestamp: Date;
  content: UserGroupContent;
  index: number;  // Ordering index within session
}

interface UserGroupContent {
  text?: string;                 // Plain text (commands removed)
  rawText?: string;              // Original text
  commands: CommandInfo[];       // Extracted /commands
  images: ImageData[];           // Attached images
  fileReferences: FileReference[]; // @file.ts mentions
}