agents md

agents.md

@@ -0,0 +1,57 @@
+# go-order-manager — agents map
+
+Thin, small service: persists the side of order events that the cart-actor
+publishes. Reads from RabbitMQ; writes orders to disk. Almost all of the
+business logic lives in `go-cart-actor`; this is the durable, simple shadow.
+
+## Where to start
+
+- `main.go` — wiring (HTTP server + RabbitMQ client + persistence).
+- `order.go` — the `Order` struct + related types.
+- `order_client.go` — `RabbitTransportClient` (the AMQP consumer) +
+  `UpdateHandler` interface.
+- `capture.go` — payment/fulfilment capture payload.
+- `README.md` — intent.
+- `deployment/order-manager.yaml` — k8s deployment (uses `AMQP_URL`).
+
+## Architecture
+
+- **Single binary, single role**: consumer of the order event stream
+  (`order-queue` on a RabbitMQ exchange).
+- **Durable record**: persists orders received via the queue; the HTTP
+  surface is mostly read/admin.
+- **No opinions on cart logic** — that's `go-cart-actor`'s domain. This
+  service is the keeper of the resulting artefacts.
+
+## Important files by area
+
+| Area                | File                                       |
+| ------------------- | ------------------------------------------ |
+| Wiring              | `main.go`                                  |
+| Domain model        | `order.go`                                 |
+| Capture payload     | `capture.go`                               |
+| AMQP consumer       | `order_client.go`                          |
+| Deploy              | `deployment/order-manager.yaml`            |
+
+## Cross-project seams
+
+- **`go-cart-actor`**: emits order events; this service consumes them. Per
+  `docs/checkout-order-handoff.md`, the ownership split is "cart-actor
+  orchestrates active checkout, order-manager owns the persisted record."
+- **RabbitMQ**: exchanges per `docs/platform-event-messaging-sketch.md`.
+
+## Improvement suggestions
+
+- **Too small to deserve its own service?** Five files, one queue consumer,
+  one model. Ask the deletion test: deleting this service would re-spread
+  "what's an order?" across two repos. Currently earns its keep. Keep it,
+  but periodically re-evaluate: if persistence moves into an outbox inside
+  cart-actor, this service dilutes into a read API and may collapse.
+- **`capture.go` is its own file but isn't clearly used** —if it's only
+  consumed by tests or an old webhook path, fold it into `order.go`.
+- **No tests.** The `OrderPlaced` and `UpdateHandler` interfaces are the
+  test surface; a 50-line test with a fake `UpdateHandler` would lock in
+  the contract that `go-cart-actor` depends on.
+- **Single `deployment/order-manager.yaml`** has no corollaries — if you're
+  adding a second env (staging), copy it explicitly into a `deploy/k8s/`
+  folder rather than hand-editing replicas later.