# 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 | File | Description | |------|-------------| | `Dockerfile` | Multi-stage Maven build → minimal JRE runtime image | | `pom.xml` | Maven project descriptor with Spring Boot and `swagger-request-validator` | | `readme.md` | Service notes: reservation lifecycle, stock schema, environment variables | | `src/main/java/com/example/inventory/InventoryApplication.java` | Spring Boot entry point | | `src/main/java/com/example/inventory/HealthController.java` | `GET /health` → `{"status": "ok"}` | | `src/main/resources/application.properties` | Server port, DB datasource settings | ## 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