agents md

agents.md

@@ -0,0 +1,102 @@
+# go-cart-actor — agents map
+
+The **commercial heart** of the platform. Orleans-style grain actors for cart,
+checkout, order, profile, inventory, plus a **UCP (Universal Commerce
+Protocol) HTTP adapter** at `internal/ucp/`. Deploys multiple binaries in
+parallel (one per concern) coordinated via k8s and an internal actor
+discovery/RPC layer. See `docs/checkout-order-handoff.md` for the role split
+with `go-order-manager`.
+
+## Where to start
+
+- `cmd/cart/main.go` — the one most commonly run in dev.
+- `pkg/actor/` — the grain framework (start with `grain.go`, then
+  `simple_grain_pool.go` and `grain_pool.go`).
+- `pkg/cart/cart-grain.go` — a concrete grain, the cleanest example.
+- `internal/ucp/handler.go` and `ucp/{cart,checkout,order,profile}.go` —
+  the protocol adapter over the grains.
+- `go-cart-actor/README.md`, `TODO.md`, `NEW_MUTATIONS_SPEC.md` — current
+  intent and known gaps.
+
+## Architecture
+
+- **Grain model**: each domain entity (cart, order, checkout…) is a grain
+  keyed by an opaque ID. Per-aggregate state machine lives in the grain's
+  `state.go`; mutations are individual `mutation_*.go` files under
+  `pkg/<domain>/` and registered through `mutation_registry.go`.
+- **RPC**: gRPC over [`proto/`](proto/) — `cart.proto`, `checkout.proto`,
+  `order.proto`, `profile.proto`, `control_plane.proto`. Pod discovery via
+  `pkg/discovery/` + `pkg/proxy/remotehost.go` (k8s host discovery in
+  `cmd/<bin>/k8s-host-discovery.go`).
+- **Binaries** (`cmd/`):
+  - `cart/`, `checkout/`, `order/`, `profile/`, `inventory/` — one each.
+  - `backoffice/` — the admin UI host, plugged into `backoffice` via
+    `pkg/backofficeadmin/`.
+  - `ucp-artifacts/` — emits the protocol artefacts (signing, handler
+    bindings).
+- **UCP**: `internal/ucp/` is the protocol adapter — it talks to the grains
+  via RPC, not directly. Separate from `pkg/{cart,checkout,…}`.
+- **Cross-cutting**: `pkg/outbox/`, `pkg/idempotency/`, `pkg/flow/`,
+  `pkg/promotions/`, `pkg/voucher/`, `pkg/telemetry/`.
+- **Auth**: `internal/customerauth/` — password hashing (`password.go`),
+  rate limit, mail notifier, redis store, opaque customer session tokens.
+
+## Important files by area
+
+| Area                       | File(s)                                                |
+| -------------------------- | ------------------------------------------------------ |
+| Grain framework            | `pkg/actor/{grain,grain_pool,simple_grain_pool,state,disk_storage}.go` |
+| Grain RPC                  | `pkg/actor/{grpc_server,grpc_server_test}.go`          |
+| Cart mutations             | `pkg/cart/mutation_*.go` (+ `cart-grain.go`)           |
+| Order mutations            | `pkg/order/mutation_*.go` + `pkg/order/order-grain.go` |
+| Order outbox / payment     | `pkg/order/{emit_created,payment,stripe,klarna}_*.go`  |
+| Promotions / vouchers      | `pkg/promotions/`, `pkg/voucher/`                      |
+| Idempotency                | `pkg/idempotency/store.go`                             |
+| Outbox (event publish)     | `pkg/outbox/outbox.go`                                 |
+| UCP protocol adapter       | `internal/ucp/{handler,cart,checkout,order,customer,profile}.go`, `signing.go` |
+| Backoffice admin           | `pkg/backofficeadmin/{app,hub,fileserver,customer}.go` |
+| Customer auth              | `internal/customerauth/{server,redis,password,tokens,mail_notifier,ratelimit}.go` |
+| Telemetry / OTel           | `pkg/telemetry/{otel,logs}.go`                         |
+| k8s service discovery      | `pkg/discovery/discovery.go`, `pkg/proxy/remotehost.go`, `cmd/<bin>/k8s-host-discovery.go` |
+| Tests integration scaffold | `cmd/cart/projection_*_test.go`, `pkg/promotions/apply_test.go` |
+
+## Cross-project seams
+
+- **`platform/`**: uses `platform/auth`, `platform/catalog`, `platform/event`,
+  `platform/inventory`, `platform/order`, `platform/tax`, `platform/rabbit`.
+- **`go-order-manager`**: subscribes to order events off the RabbitMQ
+  topology (`docs/checkout-order-handoff.md`).
+- **`go-shipping`**: pulled via HTTP from `cart` (the cart client).
+- **`slask-tracking`**: independent consumer of order events for analytics.
+- **`backoffice`** (commerce tag): exposes the `pkg/backofficeadmin/` host.
+
+## Improvement suggestions
+
+- **Mutation file explosion**: each behavior of a grain lives in its own
+  `mutation_*.go`. This is shallow — the deletion test says removing one just
+  moves the same code to its sibling file. Consider grouping related
+  mutations per feature slice (e.g. one `cart_subscription.go` for
+  add/remove/upsert subscriptiondetails), so the test surface and locality
+  live together.
+- **`pkg/cart` vs `internal/ucp` vs `pkg/checkout`** — three layers touch the
+  same conceptual "cart" entity. The UCP adapter depends on the grain, the
+  grain depends on the protocol-specific mutations, and the checkout layer
+  brokers a different view of the cart. Drop the conceptual split here:
+  consider promoting one domain (`cart`) as the seam and treating the others
+  as adapters.
+- **Inconsistent layout**: most binaries are at `cmd/<name>/main.go`, but
+  `internal/ucp/`, `internal/customerauth/`, and `pkg/voucher/`, `pkg/outbox/`
+  sit at different depths. A short module-layout doc would prevent the next
+  contributor from guessing where new helpers go.
+- **`TODO.md` and `NEW_MUTATIONS_SPEC.md` live in the repo root.** Both belong
+  in `docs/` so the README is the only thing newcomers hit first.
+- **Two proto variants**: `proto/checkout.proto` and
+  `proto/checkout/checkout.proto`. Likely a historical artefact (see
+  `proto/README` if it exists, otherwise grep `proto/` for `checkout` to see
+  which is actually imported).
+- **Test coverage is uneven across `pkg/*`** — vendor-friendly modules like
+  `pkg/promotions/` have `_test.go`, others like `pkg/voucher/` rely on
+  `parser_test.go` only. Worth a pass to seed unit tests at each public
+  function entry.
+- **`cookies.txt` at repo root** is not a build artefact and shouldn't be
+  committed.