From be473118830753fe3098e5260fdfcfc4fb792b32 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 25 Oct 2026 18:15:14 +1100 Subject: [PATCH] docs: map the services and development commands in CLAUDE.md --- CLAUDE.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index db6d109c6..0bc9e0a76 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,6 +19,25 @@ loses work, a failure that shows nothing, a security gap, a broken setup path. Give the trade-off in a sentence or two and suggest whether the request belongs in the backlog. Don't hold work back on your own judgement. +## Services and layout + +Each service is a gRPC contract in `proto//v1`, generated into +`internal/contracts//v1`, and one binary in `cmd/` that parses flags +and calls its composition root in `internal/app/`. + +| Binary | Serves | Dials | +| --- | --- | --- | +| `archie-state-store` | State Store and Control Plane contracts; owns the task and control-plane PostgreSQL tables | PostgreSQL | +| `archie-gateway` | Chat, conversation state, task tools | State Store | +| `archied` | Scheduling, workflow runs, harness, Daemon contract | State Store, Gateway, Messaging | +| `archie-messaging` | External channel frontends | Gateway | +| `archie-ui` | Dashboard HTTP API (`internal/webui`) and the embedded SPA | State Store, Gateway, daemon, harness | +| `archie-agent` | The worker inside each task container | NATS | + +`internal/domain` holds behaviour and interfaces; `internal/infrastructure` +implements them. Dashboard work follows `ui/CLAUDE.md`. Workflow YAML and its +step vocabulary are in `WORKFLOWS.md`; the server catalogue is authoritative. + ## Authority When sources disagree, the higher one wins: @@ -130,8 +149,17 @@ task build # binaries into bin/ task test # go test -short ./... task ui # dashboard into ui/dist task check # the gate + +go test -short ./internal/domain/workflow -run TestName # one test +task dev # every service + Vite at http://localhost:5173, from deployments/dev.toml +task e2e:up # seeded local stack; task e2e:check -- all runs the browser checks ``` +`task proto:generate` and `task db:generate` write the committed generated +output for `proto/` and `internal/infrastructure/postgres/`; `task check` runs +their check variants and rejects stale output. The e2e stack is not part of the +gate. + Requires Go 1.27, Task, golangci-lint, Node/npm and Docker. Adopt `task fmt` and `go fix` output as-is.