Allocation Quest
Smart Warehouse Allocation
Smart Warehouse Allocation is a stateless decision service that ranks eligible warehouses across inventory, cost, ETA, traffic, fleet, and SLA constraints, then reserves every SKU atomically in Redis.
- Atomic Multi-SKU reserve A Lua transaction either reserves the complete order at one warehouse or changes nothing.
- O(W×S) Decision path The ranking cost scales with candidate warehouses and requested SKUs.
- 500.7 Reference RPS Local single-process benchmark with in-memory data, 33 warehouses, and concurrency 25.
- 124.6ms Reference p95 Hardware-specific local benchmark result; not a production SLA.
Mission Brief
Choosing a warehouse is more than finding stock. The decision must be reproducible, explainable, and safe when many orders compete for the same inventory at the same time.
The service keeps ranking independent from reservation, rejects ambiguous inputs, and deliberately avoids split orders so downstream fulfillment receives one clear result.
System Map
Architecture
-
FastAPI Contract
Strict request models expose health, allocation, Prometheus metrics, and OpenAPI documentation.
-
Ranking Engine
Deterministic scoring filters candidates and orders them across stock, cost, ETA, traffic, fleet, and SLA factors.
-
Redis Projection
Pipelined reads provide the hot inventory and operating-state view used for low-latency decisions.
-
Lua Reservation
The highest-ranked candidate is reserved atomically, with ordered fallback when concurrency invalidates a choice.
-
Kubernetes Runtime
Probes, metrics, horizontal scaling configuration, and blue-green workflow support deployment.
Strategy Route
Battle Plan
The implementation path, checkpoint by checkpoint.
-
Checkpoint 01
Separate pure deterministic ranking from side effects so decisions can be tested and explained.
-
Checkpoint 02
Pipeline Redis reads to reduce round trips, then execute the all-SKU stock check and decrement in one Lua operation.
-
Checkpoint 03
Retry candidates in ranked order when another request wins inventory between the read and reservation steps.
-
Checkpoint 04
Keep routing and business orchestration outside the service, with outbox, CDC, and saga patterns documented as integration guidance.
-
Checkpoint 05
Expose Prometheus metrics, health probes, OpenAPI contracts, and deployment examples alongside the algorithm.
Critical Encounter
Boss Fight
-
The race between reading inventory and reserving it is the critical failure mode. A correct ranking is worthless if concurrent orders can oversell a SKU or leave half an order reserved.
Achievements Unlocked
Quest Rewards
What the quest delivered.
-
Reward 01 unlocked
Allocation remains deterministic and independently testable while the final inventory mutation is atomic.
-
Reward 02 unlocked
Ranked fallback preserves the original business priorities when the first candidate loses a concurrency race.
-
Reward 03 unlocked
The reference implementation includes the operational contracts needed to observe and deploy the service.
Special Items
Technical Loadout
- Python
- FastAPI
- Pydantic
- Redis
- Lua
- Prometheus
- OpenAPI
- Docker
- Kubernetes
Proof of Work
Explore the Quest
The 500.7 RPS and 124.6 ms p95 figures are a repository-documented local reference run, not a production SLA; results depend on hardware and workload.