matt ae4833e310 feat(planning): add project planning documents and configuration for SSH multi-context workspaces

- Introduced new planning files including PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and STATE.md to outline the vision and requirements for SSH multi-context workspaces.
- Added ARCHITECTURE.md and CONCERNS.md to detail the codebase structure and address technical debt, known bugs, and security considerations.
- Created CONVENTIONS.md to establish coding standards and practices for the project.
- Updated .gitignore to exclude demo files and added configuration for planning tools.

This commit lays the groundwork for enhancing SSH functionality and user experience in managing multiple workspaces.

2026-02-12 09:37:58 +09:00

14 KiB

Raw Blame History

Codebase Structure

Analysis Date: 2026-02-12

Directory Layout

claude-devtools/
├── src/
│   ├── main/               # Electron main process (Node.js)
│   │   ├── constants/      # Message tags, worktree patterns
│   │   ├── ipc/            # IPC handlers by domain
│   │   ├── services/       # Business logic services
│   │   │   ├── analysis/   # Chunk building, semantic steps
│   │   │   ├── discovery/  # Project/session scanning
│   │   │   ├── error/      # Error detection, triggers
│   │   │   ├── infrastructure/  # Cache, config, file watching
│   │   │   └── parsing/    # JSONL parsing, message classification
│   │   ├── types/          # Main process type definitions
│   │   ├── utils/          # Main utilities (jsonl, pathDecoder)
│   │   └── index.ts        # Main process entry point
│   ├── preload/            # Electron preload (IPC bridge)
│   │   ├── constants/      # IPC channel names
│   │   └── index.ts        # ElectronAPI implementation
│   ├── renderer/           # React application
│   │   ├── components/     # UI components by feature
│   │   │   ├── chat/       # Session message display
│   │   │   ├── common/     # Shared UI primitives
│   │   │   ├── dashboard/  # Overview pages
│   │   │   ├── layout/     # App shell, sidebars
│   │   │   ├── notifications/  # Notification UI
│   │   │   ├── search/     # Search UI
│   │   │   ├── settings/   # Settings pages
│   │   │   └── sidebar/    # Navigation
│   │   ├── constants/      # CSS variables, layout, colors
│   │   ├── contexts/       # React contexts (TabUIContext)
│   │   ├── hooks/          # Custom React hooks
│   │   ├── store/          # Zustand state management
│   │   │   ├── slices/     # Domain slices
│   │   │   └── utils/      # Store helpers
│   │   ├── types/          # Renderer type definitions
│   │   ├── utils/          # Renderer utilities
│   │   ├── App.tsx         # React root component
│   │   ├── main.tsx        # React entry point
│   │   └── index.css       # Global styles, theme
│   └── shared/             # Cross-process code
│       ├── constants/      # Cache, window, colors
│       ├── types/          # Shared type definitions
│       └── utils/          # Pure utilities
├── test/                   # Vitest tests
│   ├── main/               # Main process tests
│   │   ├── ipc/            # IPC handler tests
│   │   ├── services/       # Service tests
│   │   └── utils/          # Utility tests
│   ├── renderer/           # Renderer tests
│   │   ├── hooks/          # Hook tests
│   │   ├── store/          # Store tests
│   │   └── utils/          # Utility tests
│   └── shared/             # Shared code tests
├── resources/              # App icons, assets
├── dist/                   # Build output (renderer)
├── dist-electron/          # Build output (main, preload)
├── .claude/                # Claude Code configuration
│   ├── plans/              # Feature plans
│   └── rules/              # Project rules
├── .planning/              # GSD planning documents
│   └── codebase/           # Codebase analysis docs
├── package.json            # Dependencies, scripts
├── tsconfig.json           # TypeScript config (base)
├── tsconfig.node.json      # TypeScript config (main)
├── vite.config.ts          # Vite build config
└── vitest.config.ts        # Vitest test config

Directory Purposes

src/main/

Purpose: Electron main process - file system access, JSONL parsing, business logic
Contains: Entry point, services (5 domains), IPC handlers (10 domains), types, utilities
Key files: index.ts (app lifecycle), services/index.ts (barrel export), ipc/handlers.ts (IPC setup)

src/main/services/analysis/

Purpose: Chunk building and session analysis
Contains: ChunkBuilder, ChunkFactory, ConversationGroupBuilder, ProcessLinker, SemanticStepExtractor, SemanticStepGrouper, SubagentDetailBuilder, ToolExecutionBuilder, ToolResultExtractor, ToolSummaryFormatter
Key files: ChunkBuilder.ts (orchestrator), ChunkFactory.ts (chunk creation), SemanticStepExtractor.ts (step extraction)

src/main/services/discovery/

Purpose: Project/session scanning, subagent resolution
Contains: ProjectScanner, ProjectPathResolver, SessionSearcher, SessionContentFilter, SubagentLocator, SubagentResolver, SubprojectRegistry, WorktreeGrouper
Key files: ProjectScanner.ts (file system scanning), SubagentResolver.ts (subagent linking)

src/main/services/infrastructure/

Purpose: Core application infrastructure
Contains: DataCache, FileWatcher, ConfigManager, NotificationManager, TriggerManager, UpdaterService, SshConnectionManager, FileSystemProvider (local/SSH)
Key files: DataCache.ts (LRU cache), FileWatcher.ts (file monitoring), ConfigManager.ts (config persistence)

src/main/services/parsing/

Purpose: JSONL parsing and classification
Contains: SessionParser, MessageClassifier, ClaudeMdReader, GitIdentityResolver
Key files: SessionParser.ts (JSONL parsing), MessageClassifier.ts (message categorization)

src/main/services/error/

Purpose: Error detection and notification triggers
Contains: ErrorDetector, ErrorMessageBuilder, ErrorTriggerChecker, ErrorTriggerTester, TriggerMatcher
Key files: ErrorDetector.ts (token-based detection), TriggerMatcher.ts (pattern matching)

src/main/ipc/

Purpose: IPC request handlers organized by domain
Contains: projects, sessions, search, subagents, validation, utility, notifications, config, ssh, updater handlers
Key files: handlers.ts (registration), sessions.ts (session operations), config.ts (configuration)

src/preload/

Purpose: Secure IPC bridge between main and renderer
Contains: ElectronAPI implementation, IPC channel constants
Key files: index.ts (contextBridge API), constants/ipcChannels.ts (channel names)

src/renderer/components/chat/

Purpose: Session message display and visualization
Contains: Chat groups (User, AI, System), chat history, display items, viewers (markdown, code, diff), SessionContextPanel (visible context tracking)
Key files: ChatHistory.tsx (timeline container), AIChatGroup.tsx (AI responses), ContextBadge.tsx (per-turn context popover)

src/renderer/components/chat/items/

Purpose: Individual message/tool item renderers
Contains: BaseItem, LinkedToolItem, ExecutionTrace, SubagentItem, ThinkingItem, TextItem, SlashItem, TeammateMessageItem, MetricsPill
Key files: LinkedToolItem.tsx (tool call+result), SubagentItem.tsx (subagent display)

src/renderer/components/chat/SessionContextPanel/

Purpose: Visible context tracking panel UI
Contains: Main panel component, section wrappers, per-injection item renderers, directory tree, formatting utils
Key files: index.tsx (panel component), components/ (section wrappers), items/ (injection renderers)

src/renderer/store/

Purpose: Zustand state management
Contains: Store creation, 14 domain slices, store utilities
Key files: index.ts (store composition, IPC listeners), slices/sessionDetailSlice.ts (session data), slices/tabSlice.ts (tab management)

src/renderer/store/slices/

Purpose: Domain-specific state slices
Contains: projectSlice, repositorySlice, sessionSlice, sessionDetailSlice, subagentSlice, conversationSlice, tabSlice, tabUISlice, paneSlice, uiSlice, notificationSlice, configSlice, connectionSlice, updateSlice
Key files: sessionDetailSlice.ts (session data), tabUISlice.ts (per-tab UI state)

src/shared/

Purpose: Cross-process types and pure utilities
Contains: Type definitions (api, notifications, visualization), utilities (tokenFormatting, modelParser, logger), constants (cache, window, colors)
Key files: types/index.ts (type re-exports), utils/tokenFormatting.ts (token utilities)

test/

Purpose: Vitest unit tests
Contains: Tests organized by process (main, renderer, shared), mirrors src/ structure
Key files: main/services/analysis/ChunkBuilder.test.ts, renderer/store/sessionSlice.test.ts

Key File Locations

Entry Points:

src/main/index.ts: Main process entry (381 lines) - app lifecycle, service initialization, window creation
src/renderer/main.tsx: Renderer entry (12 lines) - React rendering
src/preload/index.ts: Preload bridge (369 lines) - ElectronAPI implementation
src/renderer/App.tsx: React root - theme, IPC listeners, layout

Configuration:

package.json: Dependencies, build scripts
tsconfig.json: Base TypeScript config
tsconfig.node.json: Main process TypeScript config
vite.config.ts: Vite build configuration
vitest.config.ts: Vitest test configuration
src/renderer/index.css: Global styles, CSS custom properties

Core Logic:

src/main/services/analysis/ChunkBuilder.ts: Chunk building orchestration
src/main/services/parsing/SessionParser.ts: JSONL parsing
src/main/services/discovery/SubagentResolver.ts: Subagent linking
src/main/services/infrastructure/DataCache.ts: LRU cache
src/main/services/infrastructure/FileWatcher.ts: File monitoring

Testing:

test/main/services/analysis/ChunkBuilder.test.ts: Chunk building tests
test/main/services/parsing/SessionParser.test.ts: JSONL parsing tests
test/renderer/store/sessionSlice.test.ts: Session state tests

Naming Conventions

Files:

Services/Components: PascalCase - ChunkBuilder.ts, SessionParser.ts, AIChatGroup.tsx
Utilities: camelCase - pathDecoder.ts, jsonl.ts, formatters.ts
Types: camelCase - messages.ts, data.ts, api.ts
Barrel exports: index.ts

Directories:

All lowercase with domain names - services/, analysis/, components/
Feature-based organization - components/chat/, components/settings/

Constants:

UPPER_SNAKE_CASE - PARALLEL_WINDOW_MS, MAX_CACHE_SESSIONS, SESSION_REFRESH_DEBOUNCE_MS

Functions:

Type guards: isXxx - isUserChunk(), isParsedRealUserMessage(), isAIChunk()
Builders: buildXxx - buildChunks(), buildSubagentDetail(), buildDisplayItems()
Getters: getXxx - getSessionPath(), getProjects(), getTaskCalls()
Creators: createXxx - createLogger(), createConfigSlice(), createWindow()

Type Guards:

Message: isParsedRealUserMessage(), isParsedInternalUserMessage(), isAssistantMessage()
Chunk: isUserChunk(), isAIChunk(), isSystemChunk(), isCompactChunk()
Context: isClaudeMdInjection(), isMentionedFileInjection(), isToolOutputInjection(), isThinkingTextInjection(), isTeamCoordinationInjection(), isUserMessageInjection()

Where to Add New Code

New Service (Main Process):

Implementation: src/main/services/{domain}/{ServiceName}.ts
Export: Add to src/main/services/{domain}/index.ts barrel
Usage: Import from @main/services or @main/services/{domain}

New IPC Handler:

Implementation: Add to existing src/main/ipc/{domain}.ts or create new domain file
Channel constant: Add to src/preload/constants/ipcChannels.ts
Registration: Add to src/main/ipc/handlers.ts if new domain
API exposure: Add method to ElectronAPI in src/preload/index.ts
Type: Update @shared/types/api.ts if needed

New React Component:

Primary code: src/renderer/components/{feature}/{ComponentName}.tsx
Feature categories: chat, common, dashboard, layout, notifications, search, settings, sidebar
Tests: test/renderer/components/{feature}/{ComponentName}.test.tsx

New Zustand Slice:

Implementation: src/renderer/store/slices/{domain}Slice.ts
Export: Add factory function create{Domain}Slice
Integration: Add to store composition in src/renderer/store/index.ts
Type: Update AppState in src/renderer/store/types.ts

New Hook:

Implementation: src/renderer/hooks/use{Name}.ts
Tests: test/renderer/hooks/use{Name}.test.ts
Import: Direct import from file (no barrel exports for hooks)

Utilities:

Main process: src/main/utils/{utilityName}.ts
Renderer: src/renderer/utils/{utilityName}.ts
Shared (pure): src/shared/utils/{utilityName}.ts

Types:

Main process only: src/main/types/{name}.ts
Renderer only: src/renderer/types/{name}.ts
Shared across processes: src/shared/types/{name}.ts

Special Directories

node_modules/

Purpose: Package dependencies
Generated: Yes (via pnpm install)
Committed: No

dist/ and dist-electron/

Purpose: Build output (production bundles)
Generated: Yes (via pnpm build)
Committed: No

.planning/codebase/

Purpose: GSD codebase analysis documents
Generated: Yes (via /gsd:map-codebase)
Committed: Yes (planning metadata)

.claude/plans/

Purpose: Feature implementation plans
Generated: Yes (via /gsd:plan-phase)
Committed: Yes (project planning)

test/mocks/

Purpose: Test fixtures and mock data
Generated: No (manually created)
Committed: Yes (test infrastructure)

resources/

Purpose: Application icons and assets
Generated: No (manually created)
Committed: Yes (app resources)