go-cart-actor/agents.md

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/ — 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.