platform/agents.md

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