Files

Lukas May 34578d39c6 refactor: Restructure monorepo to apps/server/ and apps/web/ layout

Move src/ → apps/server/ and packages/web/ → apps/web/ to adopt
standard monorepo conventions (apps/ for runnable apps, packages/
for reusable libraries). Update all config files, shared package
imports, test fixtures, and documentation to reflect new paths.

Key fixes:
- Update workspace config to ["apps/*", "packages/*"]
- Update tsconfig.json rootDir/include for apps/server/
- Add apps/web/** to vitest exclude list
- Update drizzle.config.ts schema path
- Fix ensure-schema.ts migration path detection (3 levels up in dev,
  2 levels up in dist)
- Fix tests/integration/cli-server.test.ts import paths
- Update packages/shared imports to apps/server/ paths
- Update all docs/ files with new paths

2026-03-03 11:22:53 +01:00

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