services/inventory/

Purpose

Java + Spring Boot microservice that owns the StockItem aggregate. Manages soft reservations: stock is reserved (soft-locked) during the saga window and only permanently committed after payment succeeds, or released on failure. This prevents oversell without distributed locks. Passive responder — only called by the Ordering saga. Port 5003.

Key Files

For AI Agents

Working In This Directory

• Passive service — never initiate outbound HTTP calls
• Reservation lifecycle: POST /reservations (reserve) → POST /reservations/{id}/commit (deduct) or POST /reservations/{id}/release (return)
• Invariant: reservedQty can never exceed availableQty — enforce with a row-level lock or SELECT FOR UPDATE
• POST /reservations and commit/release endpoints all require Idempotency-Key header
• On insufficient stock, return 409 with {"error": "InsufficientStock"}

Testing Requirements

• docker compose build inventory — verify Maven build
• curl http://localhost:5003/health → {"status": "ok"}
• Test reservation → commit flow; verify availableQty decreases only after commit, not after reserve
• Test reservation → release flow; verify stock returns to available pool

Common Patterns

• StockItem entity with availableQty and reservedQty fields
• Reservation entity with TTL for expiry-based cleanup (future extension)
• @Transactional(isolation = SERIALIZABLE) or SELECT FOR UPDATE on reservation creation
• Environment variables: DATABASE_URL, DATABASE_USERNAME, DATABASE_PASSWORD

Dependencies

Internal

• docs/api-specs/inventory.yaml — request validation contract
• Ordering service — sole caller

External

• Spring Boot 3.x
• swagger-request-validator (Atlassian)
• PostgreSQL — Inventory DB at port 5434
• opentelemetry-spring-boot-starter — observability