Files

Lukas May 270a5cb21d feat: Add Docker-based preview deployments for phase review

Preview deployments let reviewers spin up the app at a specific branch
in local Docker containers, accessible through a single Caddy reverse
proxy port. Docker is the source of truth — no database table needed.

New module: src/preview/ with config discovery (.cw-preview.yml →
compose → Dockerfile fallback), compose generation, Docker CLI wrapper,
health checking, and port allocation (9100-9200 range).

2026-02-10 13:24:56 +01:00

5.0 KiB

Raw Blame History

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 (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
Database	`src/db/`	Schema, repositories, migrations	database.md
Server & API	`src/server/`, `src/trpc/`	HTTP server, tRPC procedures	server-api.md
Frontend	`packages/web/`	React UI, components, hooks	frontend.md
CLI & Config	`src/cli/`, `src/config/`	CLI commands, workspace config	cli-config.md
Dispatch	`src/dispatch/`	Task/phase queue and dispatch	dispatch-events.md
Coordination	`src/coordination/`	Merge queue, conflict resolution	server-api.md
Git	`src/git/`	Worktree management, project clones	git-process-logging.md
Process	`src/process/`	Child process spawn/track/stop	git-process-logging.md
Logging	`src/logger/`, `src/logging/`	Structured logging, file capture	git-process-logging.md
Events	`src/events/`	EventBus, typed event system	dispatch-events.md
Shared	`packages/shared/`	Types shared between frontend/backend	frontend.md
Preview	`src/preview/`	Docker-based preview deployments	preview.md
Tests	`src/test/`	E2E, integration, fixtures	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)

5.0 KiB Raw Blame History