ai-workflow/docs/modules.md

Repository Modules

This repository is organized as a small monorepo with explicit module boundaries.

Top-Level Modules

Module	Path	Responsibility	Public interface	Test command
Inbox host	inbox/	Control plane: CLI, HTTP API, agent dispatch, runtime storage	CLI commands and /api/* HTTP endpoints	make test-inbox
Dashboard	dashboard/	Operations UI for the inbox host	Browser UI + calls to inbox HTTP API only	make test-dashboard
Blog backend	apps/blog/backend/	Sample service API	HTTP endpoints exposed by Express	make test-blog-backend
Blog frontend	apps/blog/frontend/	Sample client app	Browser UI + calls to blog backend HTTP API	make test-blog-frontend
Blog E2E	apps/blog/e2e/	Black-box integration tests	Playwright against running frontend/backend	make test-blog-e2e

Dependency Rules

Repository-level rules

• dashboard/ must not import code from inbox/.
• apps/blog/frontend/ must not import code from apps/blog/backend/.
• apps/blog/e2e/ must treat frontend and backend as black boxes.
• Runtime state, caches, worktrees, and local databases are generated artifacts and must not be committed.

inbox/ rules

The inbox module is the only place where repository control-plane logic should live.

• cmd/inbox/ is the executable entrypoint only.
• internal/store/ owns persistence and schema details.
• internal/httpapi/ and internal/httpservice/ own HTTP transport contracts and route wiring.
• internal/commands/, internal/cli/, and internal/web/ own CLI/Web command behavior.
• internal/*api, internal/*admin, internal/*flow, and internal/*bridge packages are application services/adapters.
• Top-level inbox/*.go files should stay as composition and compatibility wiring, not as the place where new domain logic grows.

Current workflow graph data lives in the inbox module as first-class runtime state:

• leader planning output persists to workflow_runs.command_json as structured planning
• chains carry orchestration metadata such as purpose
• tasks carry execution-graph metadata such as kind, gate_policy, deliverables, verification_mode, batch_key, and replan_policy
• task.kind = milestone is the current milestone representation; milestone nodes do not dispatch workers

Testing Strategy

Fast tests

Use module-local unit tests by default:

• make test-inbox
• make test-dashboard
• make test-blog-backend
• make test-blog-frontend

Browser/E2E tests

• make test-dashboard-e2e
• make test-blog-e2e

The blog E2E suite starts backend and frontend via Playwright webServer configuration, so it can run independently from the rest of the repository once dependencies are installed.

Workflow

1. Work in one module at a time.
2. Run that module's tests before touching cross-module integration.
3. Use HTTP or CLI contracts when crossing module boundaries.
4. Prefer adding tests in the same module that owns the behavior.