342b490fe7
Decomposed "Foundation Setup - Install Dependencies & Configure Tailwind" phase into 6 executable tasks: 1. Install Tailwind CSS, PostCSS & Autoprefixer 2. Map MUI theme to Tailwind design tokens 3. Setup CSS variables for dynamic theming 4. Install Radix UI primitives 5. Initialize shadcn/ui and setup component directory 6. Move MUI to devDependencies and verify setup Tasks follow logical dependency chain with final human verification checkpoint before proceeding with component migration. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
# Architecture Overview
|
|
|
|
Codewalk District 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)
|
|
|
|
Web UI (packages/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): `src/db/repositories/<entity>-repository.ts`
|
|
- **Adapter** (implementation): `src/db/repositories/drizzle/<entity>-repository.ts`
|
|
- Re-exported from barrel files so consumers import from `src/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 | `src/agent/` | Agent lifecycle, output parsing, accounts | [agent.md](agent.md) |
|
|
| Database | `src/db/` | Schema, repositories, migrations | [database.md](database.md) |
|
|
| Server & API | `src/server/`, `src/trpc/` | HTTP server, tRPC procedures | [server-api.md](server-api.md) |
|
|
| Frontend | `packages/web/` | React UI, components, hooks | [frontend.md](frontend.md) |
|
|
| CLI & Config | `src/cli/`, `src/config/` | CLI commands, workspace config | [cli-config.md](cli-config.md) |
|
|
| Dispatch | `src/dispatch/` | Task/phase queue and dispatch | [dispatch-events.md](dispatch-events.md) |
|
|
| Coordination | `src/coordination/` | Merge queue, conflict resolution | [server-api.md](server-api.md#coordination) |
|
|
| Git | `src/git/` | Worktree management, project clones | [git-process-logging.md](git-process-logging.md) |
|
|
| Process | `src/process/` | Child process spawn/track/stop | [git-process-logging.md](git-process-logging.md) |
|
|
| Logging | `src/logger/`, `src/logging/` | Structured logging, file capture | [git-process-logging.md](git-process-logging.md) |
|
|
| Events | `src/events/` | EventBus, typed event system | [dispatch-events.md](dispatch-events.md) |
|
|
| Shared | `packages/shared/` | Types shared between frontend/backend | [frontend.md](frontend.md) |
|
|
| Tests | `src/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) |
|