71 lines
3.3 KiB
Markdown
71 lines
3.3 KiB
Markdown
# 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).
|