66 lines
3.0 KiB
Markdown
66 lines
3.0 KiB
Markdown
# 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.
|