- 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
1.7 KiB
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 withSUM(inventory_ledger.qty)(safe at 500k+ SKUs).- Storefront listing/detail attach
available_stockonly for the current page or PDP, never the full catalog. - Checkout locks the
product_variantsrow (SELECT ... FOR UPDATE) before reserving, so concurrent COD checkouts on the same SKU cannot oversell.