Inventory correctness across concurrent order operations.

A decision that could have gone the other way

The concurrency test could have run against a mock, and it would have been faster to set up and faster in CI. It runs against a real PostgreSQL instance. A mock proves that the code calls the locking function; it cannot prove the lock holds, and holding is the entire claim.

Business problem

Order confirmation is not a simple status update. Stock must be checked and deducted atomically, two simultaneous confirmations must not oversell, cancellations must restore inventory when allowed, stale writers must be rejected, and every query must stay inside the authenticated organization.

Key engineering decisions

The application uses a router → service → repository architecture. Confirmation locks product rows in deterministic order, validates stock and order version, deducts inventory, changes state, and writes audit history in one transaction. Idempotency-Key records make identical create-order retries safe while rejecting conflicting reuse.

Reliability

Short-lived access tokens and rotating refresh tokens protect authentication. Owner, manager, staff, and viewer permissions are combined with independent tenant filtering. Standard error envelopes, X-Request-ID propagation, structured logs, audit records, liveness, readiness, migrations, Docker health checks, and a coverage gate above 90% support operations.

Results

The v1.0.0 repository release exposes versioned REST endpoints for authentication, users, customers, products, inventory, orders, transitions, and audit history. Its PostgreSQL concurrency test verifies that when stock can satisfy only one of two simultaneous confirmations, exactly one succeeds.

Technical scope

FastAPI service design, SQLAlchemy transaction boundaries, PostgreSQL row locking, optimistic concurrency, multi-tenant authorization, idempotent HTTP behavior, security decisions, database migrations, local Docker Compose runtime, testing, and observability.

Design rationale

Router, service and repository boundaries keep authorization and transaction behavior testable without adding distributed-system overhead.

Implementation status