Order Management API

A multi-tenant FastAPI backend that keeps order and inventory changes correct under retries, concurrent requests and role-scoped access.

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 released API 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, Docker deployment, testing, and observability.

POST /api/v1/orders/{id}/confirm
lock product rows → validate stock + version
commit stock deduction + state transition + audit
pytest coverage gate: ≥90%