# 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)
        └── 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) |