# 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.