# Inventory Management & Immutable Ledger Architecture ## Stock Bucket Calculation Formula $$\text{Available Stock} = \text{Physical} - \text{Reserved} - \text{POSAllocated} - \text{Damaged} - \text{OtherBlocked}$$ --- ## Ledger Event Semantics Matrix Managed via `InventoryRouter.py`. Balances are calculated by summing append-only `inventory_ledger` entries. | Ledger Event Type | Physical Change | Reserved Change | POSAllocated Change | Damaged Change | Net Available Effect | | :--- | :---: | :---: | :---: | :---: | :---: | | `RECEIPT` | $+1$ | $0$ | $0$ | $0$ | $+1$ | | `ONLINE_RESERVE` | $0$ | $+1$ | $0$ | $0$ | $-1$ | | `ONLINE_RESERVE_RELEASE` | $0$ | $-1$ | $0$ | $0$ | $+1$ | | `ONLINE_SALE_FROM_RESERVATION` | $-1$ | $-1$ | $0$ | $0$ | $0$ *(Transition)* | | `DIRECT_ONLINE_SALE` | $-1$ | $0$ | $0$ | $0$ | $-1$ | | `POS_ALLOCATION` | $0$ | $0$ | $+1$ | $0$ | $-1$ | | `POS_SALE_FROM_ALLOCATION` | $-1$ | $0$ | $-1$ | $0$ | $0$ *(Transition)* | | `DIRECT_POS_SALE` | $-1$ | $0$ | $0$ | $0$ | $-1$ | | `RETURN` | $+1$ | $0$ | $0$ | $0$ | $+1$ | | `DAMAGE` | $-1$ | $0$ | $0$ | $+1$ | $-1$ | ## Sellable catalog stock (e-commerce) Opening stock is not stored as a column on `product_variants`. Admin **Stock Qty** on product create/edit writes a ledger `RECEIPT` or `ADJUSTMENT` via `apply_stock_target`. - `GET /api/v1/inventory/skus?page&limit&q=` returns one page of sellable variants with `SUM(inventory_ledger.qty)` (safe at 500k+ SKUs). - Storefront listing/detail attach `available_stock` only for the current page or PDP, never the full catalog. - Checkout locks the `product_variants` row (`SELECT ... FOR UPDATE`) before reserving, so concurrent COD checkouts on the same SKU cannot oversell.