agents md

agents.md

@@ -0,0 +1,70 @@
+# platform — agents map
+
+A **Go library** shared across the platform — not a deployable service.
+Provides common types and adapters (auth, money, inventory, rabbit,
+catalog, tax, event, order, config). Most services depend on it via
+`go.work`.
+
+## Where to start
+
+- `platform/go.mod` — module path and consumers.
+- `doc.go` — package-level intent (if empty, add one).
+- `platform/auth/{auth,middleware}.go` — principal + scope + middleware.
+- `platform/money/money.go` — `Cents` type (the canonical money value —
+  every service uses this, **don't** add parallel types).
+- `platform/event/event.go` — generic event envelope.
+- `platform/inventory/inventory.go` — `Level` type + `ReservationPolicy`
+  interface.
+- `platform/rabbit/conn.go` — RabbitMQ connection lifecycle.
+- `platform/config/env.go` — env-var loader.
+
+## Architecture
+
+- **Cross-cutting — no business logic.** Anything here is meant to be
+  plugged into by individual services. The deletion test for any platform
+  package: "remove it; how many services have to reimplement it?" If the
+  answer is "more than one", this is the right home.
+- **Stable contracts**: changes here ripple to every service. That is the
+  cost of centralisation; pay it only when the type is reused.
+
+## Important files by area
+
+| Area         | File                                  |
+| ------------ | ------------------------------------- |
+| Auth         | `platform/auth/{auth,middleware}.go`  |
+| Money        | `platform/money/money.go`             |
+| Catalog      | `platform/catalog/{registry,schema}.go` |
+| Order        | `platform/order/order.go`             |
+| Event        | `platform/event/event.go`             |
+| Inventory    | `platform/inventory/inventory.go`     |
+| Rabbit       | `platform/rabbit/conn.go`             |
+| Config       | `platform/config/env.go`              |
+| Tax          | `platform/tax/tax.go`                 |
+
+## Cross-project seams
+
+- **Verified consumer**: `slask-finder` (`replace git.k6n.net/mats/platform
+  => ../platform` in its go.mod; line 7 + replace line 93).
+- **Likely consumers** (claimed in their respective agents.md files but not
+  cross-checked here): `go-cart-actor`, `go-redis-inventory`,
+  `go-shipping`, `slask-tracking`, `go-form-submissions`. To verify for any
+  module: `grep git.k6n.net/mats/platform <module>/go.mod`.
+
+## Improvement suggestions
+
+- **No `doc.go`** at the platform root. Add a short one that names the
+  responsibility ("shared, stable, no business logic").
+- **No tests** — but a few of these types are the contracts most services
+  build against. A `platform/money/money_test.go` for `Cents` arithmetic
+  (overflow at 2^63, rounding rules) would lock the seam.
+- **`RabbitConnection` reconnection logic lives in code.** Promote to a
+  managed component with a single `Run(ctx)` entrypoint — most services
+  copy this stub.
+- **Inventory `Level` is a single type**; if it ever needs variants
+  (per-warehouse, per-customer-group), the contract change ripples
+  everywhere. State the invariant in a top-of-file comment so future
+  contributors see the constraint.
+- **Money rounding** — ensure `Cents` cannot be divided unevenly; if you
+  have a `FromFloat`, document why it exists (and consider deprecating).
+- **`config/env.go`** — if it grows, consider whether to split into
+  `config/env` (parsing) + `config/stats` (logging).