chore(repo): reinitialize repository

2026-03-18 11:29:54 +08:00
commit 24871e213a
288 changed files with 44369 additions and 0 deletions
@@ -0,0 +1,65 @@
+# 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.