go-redis-inventory/agents.md

go-redis-inventory — agents map

Redis-backed inventory + reservation service. Tracks stock levels and runs atomic reservation operations via Lua scripts; also consumes an inventory_changed pub/sub channel to mirror upstream changes.

Where to start

• README.md — start here, it has the high-level intent.
• pkg/inventory/types.go — all the data structures (InventoryItem, InventoryReference, CartReserveRequest, …).
• pkg/inventory/redis_service.go — basic get / batch get / reserve path
  • the Lua scripts (reserveScript, reservationCheck).
• pkg/inventory/redis_reservation_service.go — cart-shaped reservations with release/availability semantics + corresponding _test.go.
• pkg/inventory/listener.go — InventoryChangeListener on the inventory_changed pub/sub channel.
• pkg/inventory/adapter.go — ReservationPolicyAdapter bridging to platform/inventory.ReservationPolicy.

Architecture

• Two responsibilities, one process: (1) hold and serve inventory state; (2) mirror upstream changes via pub/sub.
• Atomicity: reservation idempotency and TTL semantics come from Lua scripts embedded here. The scripts are the seam — if they change, the test in redis_reservation_service_test.go is the contract.
• Adapter: the ReservationPolicyAdapter is the seam to platform/inventory. Two adapters (this service and any other downstream caller) is what makes it a real seam, not a hypothetical one.

Important files by area

Area	File
Domain model	pkg/inventory/types.go
Core service	pkg/inventory/redis_service.go
Reservation service (cart)	pkg/inventory/redis_reservation_service.go
Pub/sub listener	pkg/inventory/listener.go
Platform adapter	pkg/inventory/adapter.go
Reservation tests	pkg/inventory/redis_reservation_service_test.go

Cross-project seams

• platform/inventory: implements ReservationPolicy via the adapter.
• go-cart-actor: consumes reservations through that adapter.
• Redis pub/sub: receives inventory_changed events.

Improvement suggestions

• types.go carries mixed concerns — InventoryItem (storage) sits next to CartReserveRequest (request). Split into types/ (storage-level) and types/cart.go (request) so callers can depend on only the slice they need.
• Two reservation services: redis_service.go has its own reserve, redis_reservation_service.go has another, plus a Level type (level.go). The relationship between them isn't documented; an architecture paragraph at the top of the package would help (doc.go or pkg/inventory/README.md).
• listener.go is single-channel — it consumes only inventory_changed. If more channels need the same lifecycle (reconnect, dedupe, back-off), factor out a tiny pubsub.Consumer and let the listener wrap it.
• Lua scripts live inside Go source. Promote them to .lua files, registered via //go:embed — that makes them version-controlled and testable independently of the Go code.
• No config validation. A malformed REDIS_URL/CHANNEL boots and fails at first call. Fail fast in main.go with explicit error messages.