Inventory Service

inventory-service is a Quarkus service that owns all stock data: quantities on hand, soft and hard reservations, location-level tracking, purchase orders, and inter-location transfers. Storage is PostgreSQL with store_id as a discriminator column for multi-tenant isolation.

Multiple Locations#

A store can have any number of locations. The locations table records each one with location_id, store_id, name, and type (warehouse, retail outlet, fulfilment centre, virtual). Stock is tracked per variant per location.

Stock Model#

Inventory state is held across two complementary structures.

stock_levels#

stock_levels is the current materialized view of stock for each (variant_id, location_id, store_id) combination. Columns:

Available to sell is a derived value: on_hand - soft_reserved - hard_reserved. This is the figure returned to callers and used for add-to-cart checks.

stock_movements#

stock_movements is an append-only ledger. Every stock change — regardless of source — writes an immutable row before stock_levels is updated. This provides a full audit trail and the ability to recompute stock_levels from scratch.

Supported movement types:

Reservation Lifecycle#

Reservations move through a defined lifecycle. Soft and hard reservations are held at the store’s aggregate pool level, not pinned to a specific location — location assignment is a fulfilment concern handled downstream by the order or fulfilment service.

Add to Cart#

cart-service calls PlaceSoftReservation. On success: soft_reserved++, a SOFT_RESERVATION movement is written, and a reservation_id is returned with an attached TTL. If available_to_sell is insufficient and the variant’s backorder policy is DENY, the service returns INSUFFICIENT_STOCK.

Checkout#

checkout-service calls UpgradeToHardReservation. On success: soft_reserved--, hard_reserved++, and a HARD_RESERVATION movement is written.

Order Placed#

inventory-service consumes the order.placed Kafka event. On receipt: hard_reserved--, on_hand--, and an ORDER_CONSUMED movement is written.

Soft Reservation TTL Expiry#

inventory-service manages TTL autonomously. When a soft reservation expires: soft_reserved--, a SOFT_RESERVATION_EXPIRED movement is written, and inventory.reservation_expired is published to Kafka for cart-service to act on.

Checkout Failure or Order Cancellation#

checkout-service or order-service calls ReleaseReservations. The service reverses the appropriate counts and writes SOFT_RELEASED or HARD_RELEASED movements.

Backorder Policies#

variant_inventory_settings stores per-variant configuration for how the service should behave when available_to_sell reaches zero.

The table also stores low_stock_threshold INT, which triggers the inventory.low_stock event when on_hand drops below it.

Purchase Orders#

purchase_orders and po_line_items track incoming stock from external suppliers.

Purchase order statuses: DRAFT → CONFIRMED → RECEIVED. When a purchase order is marked RECEIVED, inventory-service increments on_hand for each line item and writes a PO_RECEIVED movement.

incoming on stock_levels reflects the sum of quantities on all CONFIRMED purchase orders for that variant at that location.

Inter-Location Transfers#

stock_transfers and transfer_line_items model movement of existing stock between a store’s locations.

On processing a transfer: the source location’s on_hand is decremented and a TRANSFER_OUT movement is written; the destination location’s on_hand is incremented and a TRANSFER_IN movement is written.

gRPC Interface#

These methods are exposed to internal callers only.

Kafka Consumed#

Kafka Events Published#

Vault Configuration#