Inventory Phase A In-progress
Inventory is where merchants track physical stock - how much they have, where it lives, and every movement in or out. Owners receive goods via purchase orders, run warehouse operations through tickets, and (for F&B) auto-deduct ingredients via recipes. Every change is recorded in an immutable audit trail.
Status: In-progress · Owner: Phat · Phase: 1-3 · Last reviewed: 2026-05-31
Chain Link Roadmap Phase 1 Epic BANA-1323 - Stock control for F&B & Retail PRD Opening Balance Import · PRD-IOP-001 Stock operations F&B & Retail · PRD-PRO-001 Production orders & BOM explosion · PRD-LSE-001 Lot / serial & expiry identifiers (catalogue) URD URD Decisions (ADR) ADR-0001 Polymorphic item · ADR-0005 UoM two-layer (all) Dev docs @nx/inventory Runbook - (not yet authored) Delivery log Traceability matrix
1. Identity
| Property | Value |
|---|---|
| Module ID | CORE-06 |
| Tier | Core |
| Status | In-progress |
| Phase | P1 (Simple Stock) · P2 (Multi-location) · P3 (BOM + Advanced) |
| Priority | HIGH |
| Primary users | Owner / Manager / Cashier (read availability) |
2. Purpose & Scope
| Included | Excluded |
|---|---|
| Stock levels per item per location (on-hand, reserved, available) | Multi-currency stock valuation |
| Inventory locations (warehouses) with hierarchy + default-per-merchant | Multi-level BOM / sub-assemblies |
| Immutable audit trail of every stock movement | Recipe yield / scrap percentage |
| Vendor catalog + purchase orders with goods receipt | Full barcode-scanning integration |
| Inventory tickets (transfer, adjust, count, returns, scrap) | Stock transfer between merchants |
| Materials catalog + recipes (BOM) + runtime explosion | Inventory valuation reports (AVCO/FIFO/LIFO) |
| Production orders + unit-of-measure catalog | Lot / serial / expiry enforcement |
3. Capabilities
| Capability | What the user can do |
|---|---|
| Stock tracking | See on-hand, reserved, and available quantity per item per location. |
| Auto-deduct on sale | Stock reduces automatically when a payment succeeds. |
| Manual adjustments | Correct stock levels with typed, reason-coded movements. |
| Default location | A default warehouse is created automatically for each merchant. |
| Vendor management | Maintain a supplier catalog per merchant. |
| Purchase orders | Create POs, receive goods, and update stock through a full lifecycle. |
| Immutable audit trail | Every movement is logged with before/after quantities; never edited. |
| Multiple warehouses | Create and manage several inventory locations per merchant. |
| Inventory tickets | Run transfer, adjustment, cycle count, returns, and scrap operations. |
| Material catalog (BOM) | Track raw ingredients separately from sellable products. |
| Material recipes (BOM) | Attach versioned recipes to product variants. |
| BOM runtime explosion | Auto-deduct ingredients when a kitchen ticket item changes status. |
| Production orders | Track manufacturing with planned / actual / scrap quantities. |
| Unit-of-measure conversion | Full 3-level unit conversion beyond base ratios. |
| Low-stock alerts | Notify when stock falls below a threshold (infra ready, UI pending). |
4. Module Dependencies
| Depends on | Why |
|---|---|
| Product | Stock is tracked per product variant. |
| Commerce | Locations and vendors belong to a merchant. |
| Payment | A successful payment triggers stock deduction. |
| Used by | Why |
|---|---|
| Orders | Stock is deducted on sale. |
| Finance | PO goods receipt records a finance expense. |
| Reports | Inventory analytics and stock reporting. |
5. Backend Packages
Implementation detail lives in the developer docs - this section only maps the module to the services that power it.
| Package | Role | Developer docs |
|---|---|---|
@nx/inventory | Owns stock, locations, tracking, vendors, POs, materials/BOM, tickets; consumes sale/kitchen events. | inventory |
Engineering Mapping (Feature ⇄ Package)
The horizontal axis of the Feature Spine - each business feature (
<AREA>in the URD) maps to its engineering home. Reciprocal: the package docs link back here.
| Feature | Dev package | Status |
|---|---|---|
LOC Inventory Locations | @nx/inventory | Built |
ITM Inventory Items | @nx/inventory | Built |
STK Stock Levels | @nx/inventory | Built |
TRK Movement Audit Trail | @nx/inventory | Built |
VEN Vendors | @nx/inventory | Built |
PO Purchase Orders | @nx/inventory | Built |
POI Purchase Order Items | @nx/inventory | Built |
TKT Inventory Tickets | @nx/inventory | Built |
IOP Stock operations - F&B & Retail | @nx/inventory | Planned |
LSE Lot / Serial & Expiry Identifiers | @nx/inventory | Built |
MAT Materials | @nx/inventory | Built |
REC Recipes / BOM | @nx/inventory | In-progress |
PRO Production Orders & BOM Explosion | @nx/inventory | In-progress |
6. Key User Flows
Receive Goods (Purchase Order)
Sale Deduction
BOM Explosion (F&B Kitchen)
7. Roles & Permissions
| Role | Can | Cannot |
|---|---|---|
| Owner / Manager | Create locations, vendors, POs, tickets, materials, recipes; receive goods; adjust stock. | Edit or delete audit-trail entries. |
| Cashier | View product availability at the point of sale. | Mutate stock, POs, or tickets directly. |
| System | Auto-deduct on sale; explode recipes on kitchen events; auto-create default location. | - |
8. Status & Roadmap
| Phase | Capabilities |
|---|---|
| P1 | Stock tracking, auto-deduct on sale, manual adjustments, default location, vendors, purchase orders, immutable audit trail. |
| P2 | Multiple warehouses, location hierarchy, inventory tickets (9 types), inventory rules, landed costs. |
| P3 | Material catalog, recipes (BOM), BOM runtime explosion, production orders, UOM conversion, lot/serial tracking. |
Materials, recipes, and BOM explosion are shipped today but classified P3 because they target F&B verticals; production orders and full UOM conversion remain planned.