ifixkart-admin/docs/inventory/inventory.md
Adithiyan bbd3a3e959 feat: initial commit — full platform snapshot
- Backend: FastAPI app with all models, services, schemas, routes
- Admin Panel: Next.js dashboard with all modules
  (CRM, POS, repairs, warranties, billing, notifications, etc.)
- Ecommerce: storefront (submodule) + product catalog
- AI Agents: .agents/ skill library for Antigravity IDE
- Docs: architecture, billing, notification gateway markdown
- Submodules: Backend/OpenWA, Ecommerce/File 2/storefront
2026-10-13 12:59:47 +05:30

1.7 KiB

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.