Skip to content

CODEBASE_MAP.md

Latest commit

 

History

History
128 lines (103 loc) · 7 KB

CODEBASE_MAP.md

File metadata and controls

128 lines (103 loc) · 7 KB
Raw

Codebase Map

Navigation guide for agents and contributors. Read this first — then drill into the directory or package you need. The canonical deep-dive is AGENTS.md; this map gives you the layout so you know where to look.

Top-level layout

agent-coordinator/
  src/             Control plane (Cloudflare Worker + Durable Objects)
  packages/        Monorepo packages (chat UI, Modal infra, sandbox runtime, SDK, CLI)
  docs/            Design docs, decisions, runbooks, references
  test/            Test suites (integration, ports, controller, transport, session, …)
  scripts/         Dev workflow scripts (setup, dev-local, doctor, db-reset, cf-logs)

src/ — control plane

The Cloudflare Worker that authenticates users, routes sessions to Durable Objects, and orchestrates sandbox lifecycle.

Directory Purpose
src/index.ts Entry point. Hono app: auth middleware, REST routes, WS upgrade, cron export
src/do/ Durable Objects. README — SessionDO, OrgEventsDO, bridge event contract
src/lib/ Hexagonal port/adapter layer. README — 15 port planes; every port has interface + real adapter + fake + contract test + fault catalog
src/db/ Database schemas. README — D1 (DO routing + session index) and Postgres (Better Auth + app data)
src/contracts/ Type definitions. Agent run contract, policy enforcement, secrets, environment profiles, usage
src/schemas/ Generated schemas. Bridge protocol types, platform event types
src/cron/ Scheduled jobs. Repo image build cron (gated off by default)
src/env.ts Environment config. Void defineEnv schema

How to navigate src/

  1. Adding a route? Start at src/index.ts — it's the single Hono entry point
  2. Debugging session lifecycle? src/do/session-do.ts (130KB — use the section map in src/do/README.md)
  3. Adding a sandbox provider? src/lib/sandbox/ — implement the SandboxProvider interface
  4. Changing auth? src/lib/route-auth.ts for middleware, src/lib/identity/ for the port
  5. Changing the database? src/db/schema.ts for D1, src/db/pg/ for Postgres migrations

packages/ — monorepo

Package Language Purpose
chat/ TypeScript Main UI. Void + Vite, assistant-ui shell, warm theme. npm run dev
modal-infra/ Python Modal data plane. Sandbox lifecycle API, GitHub App tokens, image definitions
sandbox-runtime/ Python Runs inside every sandbox. Supervisor entrypoint, bridge, OpenCode integration
acp-client/ TypeScript ACP client. Agent Communication Protocol client for talking to ACP servers
sdk/ TypeScript External SDK. Consumed by downstream users of the agent-coordinator API
cli/ TypeScript CLI tool. Command-line interface for the platform
web/ TypeScript Older web app. Predecessor to chat/ — check status before modifying
assistant-adapter/ TypeScript Adapter. Bridges assistant-ui runtime to agent-coordinator backend
tool-renderers/ TypeScript Tool UI cards. Renders tool call outputs in the chat UI
deploy/ TypeScript Deploy CLI. Wraps acdeploy for prod deployment
devtools/ TypeScript Dev tools. acdev CLI for local dependency management

Which package do I need?

  • Building UI? packages/chat/
  • Debugging sandbox execution? packages/sandbox-runtime/ (Python, runs inside sandbox) + src/do/session-do.ts (TypeScript, runs in DO)
  • Deploying infrastructure? packages/modal-infra/ + packages/deploy/
  • Integrating as a consumer? packages/sdk/

docs/ — documentation

Directory What's there
docs/decisions/ Living source of truth. ADRs, current state, fault catalog, rules for agents
docs/design/ Design materials. Target architecture, as-built review, port catalog, sandbox designs
docs/references/ Deep-dive explainers. 01–05: the "why" behind DO, spawn flow, bridge protocol, event flow
docs/runbooks/ Operations. Scanning errors, GitHub OAuth verification
docs/handoff/ Session handoff notes. Point-in-time snapshots, task records
docs/gaps-and-issues/ Living gap catalog. What's built vs planned, known issues
docs/adr/ Redirect only. Its one ADR moved to docs/decisions/adr/0009 (run store) — NOT superseded; orthogonal topic. One ADR registry now: docs/decisions/adr/
docs/cutover-guide/ Interactive dashboard. Sprint status, architecture map, data flow

Reading order for new agents

  1. This file (CODEBASE_MAP.md) — layout and navigation
  2. AGENTS.md — canonical guide with invariants, commands, architecture
  3. docs/decisions/README.md — current state and active decisions
  4. docs/references/ — read 01→05 for the deep "why"
  5. Drill into the directory/package you need

test/ — test suites

test/
  integration/      Full lifecycle tests (walking-skeleton, disruption)
  ports/            Port contract tests (conformance registry, fake contracts)
  controller/       Agent controller tests
  transport/        WebSocket transport tests
  session/          Session state tests
  sandbox/          Sandbox provider tests
  governance/       Auth and routing tests
  acceptance/       End-to-end acceptance tests

Run: npm test (Vitest, Workers pool, real DO + D1).

Key invariants (don't break these)

  1. DO ID format: {organizationId}:{sessionId} — tenant isolation by construction
  2. resolveContext is the sole org resolver — never read member directly
  3. System vars override user secrets for RESERVED_SYSTEM_KEYS — do not reorder the merge
  4. Never import a concrete adapter outside create-controller.ts — enforced by scripts/check-composition-root.ts
  5. Every port must have a fake + fault catalog — enforced by test/ports/conformance-registry.test.ts
  6. Never edit generated files: src/db/auth-schema.ts, worker-configuration.d.ts
  7. Modal deploy: modal deploy deploy.py only, never modal deploy src/app.py

Quick reference: common tasks

Task Start here
Add a new API route src/index.ts
Debug a session hang src/do/session-do.ts (alarm lifecycle)
Add a sandbox provider src/lib/sandbox/provider.ts → implement interface
Add a new port src/lib/<plane>/ → create interface + fake + real adapter + contract test + fault catalog
Change auth behavior src/lib/route-auth.ts
Change DB schema src/db/schema.ts (D1) or src/db/pg/ (Postgres) → npm run db:generate
Run a single test npx vitest run test/<path> -t "test name"
Deploy npm run deploy:control-plane (or npm run deploy:all)
Check health npm run doctor

Last updated: 2026-06-07. Generated from the folder-structure-blueprint-generator skill template.