ros/automaker
1
0
Fork 0
mirror of https://github.com/AutoMaker-Org/automaker.git synced 2026-02-01 20:23:36 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
5a5c56a4cfff9d7d1a84e728d0a8ea072365c45b
automaker/.planning/codebase/STRUCTURE.md
Shirone c30cde242a docs: map existing codebase 
- STACK.md - Technologies and dependencies
- ARCHITECTURE.md - System design and patterns
- STRUCTURE.md - Directory layout
- CONVENTIONS.md - Code style and patterns
- TESTING.md - Test structure
- INTEGRATIONS.md - External services
- CONCERNS.md - Technical debt and issues
2026-01-27 13:48:24 +01:00

341 lines
14 KiB
Markdown
Raw Blame History

# 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_
Reference in New Issue View Git Blame Copy Permalink