automaker/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-01-27

Directory Layout

automaker/
├── apps/                        # Application packages
│   ├── ui/                      # React + Electron frontend (port 3007)
│   │   ├── src/
│   │   │   ├── main.ts          # Electron/Vite entry point
│   │   │   ├── app.tsx          # Root React component (splash, router)
│   │   │   ├── renderer.tsx     # Electron renderer entry
│   │   │   ├── routes/          # TanStack Router file-based routes
│   │   │   ├── components/      # React components (views, dialogs, UI, layout)
│   │   │   ├── store/           # Zustand state management
│   │   │   ├── hooks/           # Custom React hooks
│   │   │   ├── lib/             # Utilities (API client, electron, queries, etc.)
│   │   │   ├── electron/        # Electron main & preload process files
│   │   │   ├── config/          # UI configuration (fonts, themes, routes)
│   │   │   └── styles/          # CSS and theme files
│   │   ├── public/              # Static assets
│   │   └── tests/               # E2E Playwright tests
│   │
│   └── server/                  # Express backend (port 3008)
│       ├── src/
│       │   ├── index.ts         # Express app initialization, route mounting
│       │   ├── routes/          # REST API endpoints (30+ route folders)
│       │   ├── services/        # Business logic services
│       │   ├── providers/       # AI model provider implementations
│       │   ├── lib/             # Utilities (events, auth, helpers, etc.)
│       │   ├── middleware/      # Express middleware
│       │   └── types/           # Server-specific type definitions
│       └── tests/               # Unit tests (Vitest)
│
├── libs/                        # Shared npm packages (@automaker/*)
│   ├── types/                   # @automaker/types (no dependencies)
│   │   └── src/
│   │       ├── index.ts         # Main export with all type definitions
│   │       ├── feature.ts       # Feature, FeatureStatus, etc.
│   │       ├── provider.ts      # Provider interfaces, model definitions
│   │       ├── settings.ts      # Global and project settings types
│   │       ├── event.ts         # Event types for real-time updates
│   │       ├── session.ts       # AgentSession, conversation types
│   │       ├── model*.ts        # Model-specific types (cursor, codex, gemini, etc.)
│   │       └── ... 20+ more type files
│   │
│   ├── utils/                   # @automaker/utils (logging, errors, images, context)
│   │   └── src/
│   │       ├── logger.ts        # createLogger() with LogLevel enum
│   │       ├── errors.ts        # classifyError(), error types
│   │       ├── image-utils.ts   # Image processing, base64 encoding
│   │       ├── context-loader.ts # loadContextFiles() for AI prompts
│   │       └── ... more utilities
│   │
│   ├── platform/                # @automaker/platform (paths, security, OS)
│   │   └── src/
│   │       ├── index.ts         # Path getters (getFeatureDir, getFeaturesDir, etc.)
│   │       ├── secure-fs.ts     # Secure filesystem operations
│   │       └── config/          # Claude auth detection, allowed paths
│   │
│   ├── prompts/                 # @automaker/prompts (AI prompt templates)
│   │   └── src/
│   │       ├── index.ts         # Main prompts export
│   │       └── *-prompt.ts      # Prompt templates for different features
│   │
│   ├── model-resolver/          # @automaker/model-resolver
│   │   └── src/
│   │       └── index.ts         # resolveModelString() for model aliases
│   │
│   ├── dependency-resolver/     # @automaker/dependency-resolver
│   │   └── src/
│   │       └── index.ts         # Resolve feature dependencies
│   │
│   ├── git-utils/               # @automaker/git-utils (git operations)
│   │   └── src/
│   │       ├── index.ts         # getGitRepositoryDiffs(), worktree management
│   │       └── ... git helpers
│   │
│   ├── spec-parser/             # @automaker/spec-parser
│   │   └── src/
│   │       └── ... spec parsing utilities
│   │
│   └── tsconfig.base.json       # Base TypeScript config for all packages
│
├── .automaker/                  # Project data directory (created by app)
│   ├── features/                # Feature storage
│   │   └── {featureId}/
│   │       ├── feature.json     # Feature metadata and content
│   │       ├── agent-output.md  # Agent execution results
│   │       └── images/          # Feature images
│   ├── context/                 # Context files (CLAUDE.md, etc.)
│   ├── settings.json            # Per-project settings
│   ├── spec.md                  # Project specification
│   └── analysis.json            # Project structure analysis
│
├── data/                        # Global data directory (default, configurable)
│   ├── settings.json            # Global settings, profiles
│   ├── credentials.json         # Encrypted API keys
│   ├── sessions-metadata.json   # Chat session metadata
│   └── agent-sessions/          # Conversation histories
│
├── .planning/                   # Generated documentation by GSD orchestrator
│   └── codebase/               # Codebase analysis documents
│       ├── ARCHITECTURE.md     # Architecture patterns and layers
│       ├── STRUCTURE.md        # This file
│       ├── STACK.md            # Technology stack
│       ├── INTEGRATIONS.md     # External API integrations
│       ├── CONVENTIONS.md      # Code style and naming
│       ├── TESTING.md          # Testing patterns
│       └── CONCERNS.md         # Technical debt and issues
│
├── .github/                     # GitHub Actions workflows
├── scripts/                     # Build and utility scripts
├── tests/                       # Test data and utilities
├── docs/                        # Documentation
├── package.json                 # Root workspace config
├── package-lock.json            # Lock file
├── CLAUDE.md                    # Project instructions for Claude Code
├── DEVELOPMENT_WORKFLOW.md      # Development guidelines
└── README.md                    # Project overview

Directory Purposes

apps/ui/:

• Purpose: React frontend for desktop (Electron) and web modes
• Build system: Vite 7 with TypeScript
• Styling: Tailwind CSS 4
• State: Zustand 5 with API persistence
• Routing: TanStack Router with file-based structure
• Desktop: Electron 39 with preload IPC bridge

apps/server/:

• Purpose: Express backend API and service layer
• Build system: TypeScript → JavaScript
• Runtime: Node.js 18+
• WebSocket: ws library for real-time streaming
• Process management: node-pty for terminal isolation

libs/types/:

• Purpose: Central type definitions (no dependencies, fast import)
• Used by: All other packages and apps
• Pattern: Single namespace export from index.ts
• Build: Compiled to ESM only

libs/utils/:

• Purpose: Shared utilities for logging, errors, file operations, image processing
• Used by: Server, UI, other libraries
• Notable: createLogger(), classifyError(), loadContextFiles(), readImageAsBase64()

libs/platform/:

• Purpose: OS-agnostic path management and security enforcement
• Used by: Server services for file operations
• Notable: Path normalization, allowed directory enforcement, Claude auth detection

libs/prompts/:

• Purpose: AI prompt templates injected into agent context
• Used by: AgentService when executing features
• Pattern: Function exports that return prompt strings

Key File Locations

Entry Points:

Server:

• apps/server/src/index.ts: Express server initialization, route mounting, WebSocket setup

UI (Web):

• apps/ui/src/main.ts: Vite entry point
• apps/ui/src/app.tsx: Root React component

UI (Electron):

• apps/ui/src/main.ts: Vite entry point
• apps/ui/src/electron/main-process.ts: Electron main process
• apps/ui/src/preload.ts: Electron preload script for IPC bridge

Configuration:

• apps/server/src/index.ts: PORT, HOST, HOSTNAME, DATA_DIR env vars
• apps/ui/src/config/: Theme options, fonts, model aliases
• libs/types/src/settings.ts: Settings schema
• .env.local: Local development overrides (git-ignored)

Core Logic:

Server:

• apps/server/src/services/agent-service.ts: AI agent execution engine (31KB)
• apps/server/src/services/auto-mode-service.ts: Feature batching and automation (216KB - largest)
• apps/server/src/services/feature-loader.ts: Feature persistence and loading
• apps/server/src/services/settings-service.ts: Settings management
• apps/server/src/providers/provider-factory.ts: AI provider selection

UI:

• apps/ui/src/store/app-store.ts: Global state (84KB - largest frontend file)
• apps/ui/src/lib/http-api-client.ts: API client with auth (92KB)
• apps/ui/src/components/views/board-view.tsx: Kanban board (70KB)
• apps/ui/src/routes/__root.tsx: Root layout with session init (32KB)

Testing:

E2E Tests:

• apps/ui/tests/: Playwright tests organized by feature area
  • settings/, features/, projects/, agent/, utils/, context/

Unit Tests:

• libs/*/tests/: Package-specific Vitest tests
• apps/server/src/tests/: Server integration tests

Test Config:

• vitest.config.ts: Root Vitest configuration
• apps/ui/playwright.config.ts: Playwright configuration

Naming Conventions

Files:

• Components: PascalCase.tsx (e.g., board-view.tsx, session-manager.tsx)
• Services: camelCase-service.ts (e.g., agent-service.ts, settings-service.ts)
• Hooks: use-kebab-case.ts (e.g., use-auto-mode.ts, use-settings-sync.ts)
• Utilities: camelCase.ts (e.g., api-fetch.ts, log-parser.ts)
• Routes: kebab-case with index.ts pattern (e.g., routes/agent/index.ts)
• Tests: _.test.ts or _.spec.ts (co-located with source)

Directories:

• Feature domains: kebab-case (e.g., auto-mode/, event-history/, project-settings-view/)
• Type categories: kebab-case plural (e.g., types/, services/, providers/, routes/)
• Shared utilities: kebab-case (e.g., lib/, utils/, hooks/)

TypeScript:

• Types: PascalCase (e.g., Feature, AgentSession, ProviderMessage)
• Interfaces: PascalCase (e.g., EventEmitter, ProviderFactory)
• Enums: PascalCase (e.g., LogLevel, FeatureStatus)
• Functions: camelCase (e.g., createLogger(), classifyError())
• Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_TIMEOUT_MS, MAX_RETRIES)
• Variables: camelCase (e.g., featureId, settingsService)

Where to Add New Code

New Feature (end-to-end):

• API Route: apps/server/src/routes/{feature-name}/index.ts
• Service Logic: apps/server/src/services/{feature-name}-service.ts
• UI Route: apps/ui/src/routes/{feature-name}.tsx (simple) or {feature-name}/ (complex with subdir)
• Store: apps/ui/src/store/{feature-name}-store.ts (if complex state)
• Tests: apps/ui/tests/{feature-name}/ or apps/server/src/tests/

New Component/Module:

• View Components: apps/ui/src/components/views/{component-name}/
• Dialog Components: apps/ui/src/components/dialogs/{dialog-name}.tsx
• Shared Components: apps/ui/src/components/shared/ or components/ui/ (shadcn)
• Layout Components: apps/ui/src/components/layout/

Utilities:

• New Library: Create in libs/{package-name}/ with package.json and tsconfig.json
• Server Utilities: apps/server/src/lib/{utility-name}.ts
• Shared Utilities: Extend libs/utils/src/ or create new lib if self-contained
• UI Utilities: apps/ui/src/lib/{utility-name}.ts

New Provider (AI Model):

• Implementation: apps/server/src/providers/{provider-name}-provider.ts
• Types: Add to libs/types/src/{provider-name}-models.ts
• Model Resolver: Update libs/model-resolver/src/index.ts with model alias mapping
• Settings: Update libs/types/src/settings.ts for provider-specific config

Special Directories

apps/ui/electron/:

• Purpose: Electron-specific code (main process, IPC handlers, native APIs)
• Generated: Yes (preload.ts)
• Committed: Yes

apps/ui/public/

• Purpose: Static assets (sounds, images, icons)
• Generated: No
• Committed: Yes

apps/ui/dist/:

• Purpose: Built web application
• Generated: Yes
• Committed: No (.gitignore)

apps/ui/dist-electron/:

• Purpose: Built Electron app bundle
• Generated: Yes
• Committed: No (.gitignore)

.automaker/features/{featureId}/:

• Purpose: Per-feature persistent storage
• Structure: feature.json, agent-output.md, images/
• Generated: Yes (at runtime)
• Committed: Yes (tracked in project git)

data/:

• Purpose: Global data directory (global settings, credentials, sessions)
• Generated: Yes (created at first run)
• Committed: No (.gitignore)
• Configurable: Via DATA_DIR env var

node_modules/:

• Purpose: Installed dependencies
• Generated: Yes
• Committed: No (.gitignore)

dist/, build/:

• Purpose: Build artifacts
• Generated: Yes
• Committed: No (.gitignore)

---

Structure analysis: 2026-01-27