docs: map the services and development commands in CLAUDE.md

This commit is contained in:
sam committed 2026-10-25 18:15:14 +11:00
1 parent 1e9659c7a2
commit be47311883
1 file changed
+28
+28
View File
@@ -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. </temporary>
## Services and layout
Each service is a gRPC contract in `proto/<service>/v1`, generated into
`internal/contracts/<service>/v1`, and one binary in `cmd/` that parses flags
and calls its composition root in `internal/app/<service>`.
| 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.