Stockroom — Inventory and Orders Under Load

The problem

Stock is the classic contended resource. The naive version reads the quantity, checks it is enough and writes the new value, and under concurrency it oversells, because two requests can both read “1” before either writes “0”. When an order cannot go through, the customer also deserves to know why: not enough stock, a busy moment worth retrying, and a server that is down are three different situations.

How it’s built

Overselling is refused in three independent places, because any one of them could be bypassed by a future change: a database CHECK constraint that stock never goes below zero, an optimistic-lock version column so concurrent writers collide instead of overwriting, and a domain method as the only way to remove stock. A lost race is retried up to three times in a fresh transaction, then answered honestly with a retryable error. Errors are RFC 7807 problem documents, and the front end keeps “out of stock”, “try again” and “unreachable” as three distinct results.

What it does

• Twenty simultaneous orders for five units: exactly five succeed and stock lands on zero
• Prices copied onto order lines, so past orders show what was actually paid
• Out of stock, try again and server unreachable shown as three different messages
• Schema owned by Flyway migrations, checked against the code at startup
• Concurrency test against real PostgreSQL 16 through Testcontainers in CI