# 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).