0ff65b0b02
Update all user-facing strings (HTML title, manifest, header logo, browser title updater), code comments, and documentation references. Folder name retained as-is.
112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
# Architecture Overview
|
|
|
|
Codewalkers is a multi-agent workspace that orchestrates multiple AI coding agents (Claude, Codex, etc.) working in parallel on a shared codebase.
|
|
|
|
## System Diagram
|
|
|
|
```
|
|
CLI (cw)
|
|
└── CoordinationServer
|
|
├── HTTP Server (node:http, port 3847)
|
|
│ ├── GET /health
|
|
│ ├── GET /status
|
|
│ └── POST /trpc/* → tRPC Router (68+ procedures)
|
|
├── EventBus (typed pub/sub, 30+ event types)
|
|
├── MultiProviderAgentManager
|
|
│ ├── ProcessManager (detached child processes)
|
|
│ ├── WorktreeManager (git worktrees per agent)
|
|
│ ├── OutputHandler (JSONL stream parsing)
|
|
│ ├── AccountManager (round-robin, exhaustion failover)
|
|
│ └── LifecycleController (retry, signal recovery)
|
|
├── DispatchManager (task queue, dependency resolution)
|
|
├── PhaseDispatchManager (phase queue, DAG ordering)
|
|
├── CoordinationManager (merge queue, conflict resolution)
|
|
└── PreviewManager (Docker-based preview deployments)
|
|
|
|
Web UI (apps/web/)
|
|
└── React 19 + TanStack Router + tRPC React Query
|
|
├── Initiative management (CRUD, projects)
|
|
├── Page editor (Tiptap rich text)
|
|
├── Pipeline visualization (phase DAG)
|
|
├── Execution tab (task dispatch, agent monitoring)
|
|
└── Review tab (proposal accept/dismiss)
|
|
```
|
|
|
|
## Architectural Patterns
|
|
|
|
### Hexagonal Architecture (Ports & Adapters)
|
|
Every data-access layer follows this pattern:
|
|
- **Port** (interface): `apps/server/db/repositories/<entity>-repository.ts`
|
|
- **Adapter** (implementation): `apps/server/db/repositories/drizzle/<entity>-repository.ts`
|
|
- Re-exported from barrel files so consumers import from `apps/server/db/`
|
|
|
|
### Event-Driven Communication
|
|
All inter-module communication flows through a typed `EventBus`:
|
|
- Managers emit domain events (agent:spawned, task:completed, etc.)
|
|
- tRPC subscriptions bridge events to the frontend via SSE
|
|
- Dispatch/coordination reacts to task/phase lifecycle events
|
|
|
|
### Data-Driven Provider Configuration
|
|
Agent providers (Claude, Codex, etc.) are defined as configuration objects, not code:
|
|
- `AgentProviderConfig` specifies command, args, resume style, prompt mode
|
|
- `buildSpawnCommand()` / `buildResumeCommand()` are generic and data-driven
|
|
|
|
## Module Map
|
|
|
|
| Module | Path | Purpose | Docs |
|
|
|--------|------|---------|------|
|
|
| Agent | `apps/server/agent/` | Agent lifecycle, output parsing, accounts | [agent.md](agent.md) |
|
|
| Database | `apps/server/db/` | Schema, repositories, migrations | [database.md](database.md) |
|
|
| Server & API | `apps/server/server/`, `apps/server/trpc/` | HTTP server, tRPC procedures | [server-api.md](server-api.md) |
|
|
| Frontend | `apps/web/` | React UI, components, hooks | [frontend.md](frontend.md) |
|
|
| CLI & Config | `apps/server/cli/`, `apps/server/config/` | CLI commands, workspace config | [cli-config.md](cli-config.md) |
|
|
| Dispatch | `apps/server/dispatch/` | Task/phase queue and dispatch | [dispatch-events.md](dispatch-events.md) |
|
|
| Coordination | `apps/server/coordination/` | Merge queue, conflict resolution | [server-api.md](server-api.md#coordination) |
|
|
| Git | `apps/server/git/` | Worktree management, project clones | [git-process-logging.md](git-process-logging.md) |
|
|
| Process | `apps/server/process/` | Child process spawn/track/stop | [git-process-logging.md](git-process-logging.md) |
|
|
| Logging | `apps/server/logger/`, `apps/server/logging/` | Structured logging, file capture | [git-process-logging.md](git-process-logging.md) |
|
|
| Events | `apps/server/events/` | EventBus, typed event system | [dispatch-events.md](dispatch-events.md) |
|
|
| Shared | `packages/shared/` | Types shared between frontend/backend | [frontend.md](frontend.md) |
|
|
| Preview | `apps/server/preview/` | Docker-based preview deployments | [preview.md](preview.md) |
|
|
| Tests | `apps/server/test/` | E2E, integration, fixtures | [testing.md](testing.md) |
|
|
|
|
## Entity Relationships
|
|
|
|
```
|
|
INITIATIVES (root aggregate)
|
|
├── N PHASES (with phase_dependencies DAG)
|
|
│ └── N TASKS
|
|
├── N TASKS (initiative-level, with task_dependencies DAG)
|
|
│ └── N TASKS (parentTaskId self-ref for decomposition)
|
|
├── N PAGES (parentPageId self-ref for hierarchy)
|
|
├── N INITIATIVE_PROJECTS (junction → PROJECTS M:M)
|
|
└── N PROPOSALS
|
|
|
|
AGENTS (independent aggregate)
|
|
├── → TASK (optional)
|
|
├── → INITIATIVE (optional)
|
|
├── → ACCOUNT (optional)
|
|
├── N PROPOSALS
|
|
└── N MESSAGES (sender/recipient)
|
|
|
|
ACCOUNTS → N AGENTS
|
|
AGENT_LOG_CHUNKS (no FK, survives agent deletion)
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|-----------|
|
|
| Runtime | Node.js (ESM) |
|
|
| Language | TypeScript (strict) |
|
|
| Database | SQLite via better-sqlite3 + Drizzle ORM |
|
|
| HTTP | Native node:http |
|
|
| API | tRPC v11 |
|
|
| Frontend | React 19, TanStack Router, Tailwind CSS, shadcn/ui |
|
|
| Editor | Tiptap (ProseMirror) |
|
|
| Git | simple-git |
|
|
| Process | execa (detached) |
|
|
| Logging | pino (structured) |
|
|
| Testing | vitest |
|
|
| Build | tsup (server), Vite (frontend) |
|