PRD: Bill of Materials

Module	Inventory	PRD ID	PRD-BOM-001
Status	No item	FEAT	BOM
Epic	—	Plane	—
Date	2026-07-13	Version	v1.0
Packages	@nx/inventory	URD	BOM
Surface	Client · Owner/MgrSale · POS
Owner	Phát Nguyễn

What a bill of materials is

A bill of materials (Recipe) is the quantity sheet of one item: one glass of milk tea takes 50ml of milk, 5g of tea, 30g of pearls. The owner writes it once on the Bill of Materials screen in the Inventory area of a merchant (Merchant), and both the POS and production orders read that same sheet.

A bill of materials works directly on the stock of each inventory location (InventoryLocation): tapping an item into the order reserves the materials (Material), and completing the order is when the materials physically leave the location.

The four stock numbers

Lifted from Stock Items & Levels so you do not have to open another PRD. Every item at every location carries four numbers:

Number	What the system calls it	Meaning
On hand	on-hand	Goods physically sitting at the location
Reserved	reserved	Already promised to another document, no longer sellable to anyone else
Available	available	The part still on offer
Incoming	incoming	Already left the source location, not yet arrived at the destination

The invariant, true at every moment:

Available = On hand - Reserved

Reserving materials at tap time moves stock from available into reserved. On hand only drops when the order completes.

Why a bill of materials is more than a quantity sheet

An F&B merchant does not sell "a can of soda", it sells "a glass of milk tea". What sits in the store room is milk, tea, pearls and sugar. What the customer orders is a name on the menu.

The owner's hard problem is not writing the recipe, it is the three questions that come with it. When this item sells, what gets drawn down: the item itself, or its materials? When do we know it has run out: finding out the milk is gone after the customer has already paid is far too late. And when does the ledger move: at tap time, at payment, or when the kitchen finishes the dish?

BANA answers the first question by adding no mode switch at all. The product catalog already carries the item type and a track-stock flag. Those two together derive every drawdown path, wrapped in one matrix that closes off every combination. A third flag would only spawn contradictory combinations that nobody can explain.

Second question: check and reserve the materials the moment the item is tapped into the order, not after the money is collected. Third question: deduct from the ledger at payment by default, and merchants running a kitchen display turn on an option that moves it to when the kitchen marks the item done.

A bowl of pho from start to finish

Broth is a semi-finished item with stock tracking on: it has stock of its own. The bowl-of-pho recipe calls for 200ml of broth. The pot-of-broth recipe calls for 5kg of bones per 50 litres.

What happens	Bones (kg)	Broth on hand (l)	Broth reserved (l)
Start of shift: 15kg of bones on hand, no broth yet	15	0	0
A production order cooks a 50-litre pot, eating 5kg of bones	10	50	0
The cashier taps 1 bowl of pho into the order	10	50	0.2
The customer pays, the order completes	10	49.8	0

• The bones are deducted exactly once, at the production order that cooked the pot of broth.
• Selling the bowl of pho draws down broth only. The explosion stops at broth, because broth has stock of its own.
• Tapping the item into the order reserves 200ml, it does not deduct. Broth on hand only drops when the order completes.

The easiest thing to get wrong

Explosion STOPS at every component that has STOCK OF ITS OWN

The deciding question is "does this component have its own stock", not "does this component have a nested recipe".

The pot of broth above was cooked by a production order, and that order already deducted 5kg of bones. If selling a bowl of pho made the system explode THROUGH the broth down to the bones, those same 5kg of bones would be deducted a second time. The book would report the bones gone while the bones are still sitting on the shelf.

Only recurse through a component with no stock of its own, meaning a prepared item. A component that has stock of its own is drawn down on that stock and the explosion stops right there.

Consequence: running out of broth mid-shift sends broth stock negative with a warning. The system does not deduct bones to make up for it. That negative number is exactly the signal that the kitchen cooked more without logging a production order.

1. Goals & Non-goals

Goals

• Let an owner write the bill of materials for an item: the component list, quantities, units of measure, optional components.
• Lock in one single "item type x track-stock flag" matrix that decides how stock is drawn down, with no extra mode switch.
• Let only two types, prepared items and manufactured goods, go through a bill of materials; every other type never explodes a BOM, even with one attached.
• Explode a bill of materials across multiple levels, but stop at every component that has stock of its own; with a depth limit and a cycle guard.
• Check and reserve materials the moment the item is tapped into the order, and report shortages right in the cart.
• Compute how many portions of an item are still sellable from the materials left, and show "sold out" on the POS menu.
• Deduct materials from the ledger when the order is paid, or when the kitchen marks the item done if the merchant chooses that.

Non-goals

• Production orders (drafting, running, completing, closing a finished-goods lot) belong to the Production Order feature. This PRD only defines the bill of materials that a production order runs against.
• The reservation mechanism in general (who holds stock, releasing stock, allow oversell at item level) belongs to the Stock Reservation feature. This PRD only covers the part of it a bill of materials passes through.
• Item pricing and finished-goods inventory valuation.
• Standard waste allowance and yield per batch.
• Auto-suggested recipes or industry-standard recipe templates.

2. Success metrics

Metric	Target / signal
Sold-out caught early	Cases where the material shortage is only discovered after the customer has paid drop to near 0
Material stock matches reality	The gap between book stock and hand-counted stock for F&B materials narrows across stock count periods
No stuck reservations	No material sits reserved forever after its order has closed
BOM coverage	Every F&B item on the merchant's menu has an active bill of materials

3. Personas & scenarios

Persona	Goal in this feature
Owner / Manager	Write the bill of materials for each item, set the item type and the track-stock flag, choose when the ledger moves
Cashier	Tap an item into the order and know immediately whether it can still be made, before the customer pays
Kitchen staff	Mark an item done or void it, and trust that stock is drawn down to match what was actually made

Core scenario: the owner writes the milk tea bill of materials - milk, tea, pearls - on the Bill of Materials screen, and sets milk tea as a prepared item that tracks stock. The cashier taps "1 milk tea" on the POS. The system explodes the bill of materials, checks the three materials, reserves enough for this glass and drops the item into the cart. The customer pays. The materials leave the location for real, and the milk on hand drops by 50ml.

4. User stories

#	As a	I want	So that
01	owner	to write the bill of materials for milk tea	selling one glass draws down the milk, tea and pearls by itself instead of me deducting them by hand at closing
02	owner	a can of soda to draw down one-for-one on itself while milk tea draws down its materials	I never have to learn a new configuration flag
03	owner	a chicken rice combo to draw down exactly one rice and one chicken portion	I do not have to write a duplicate recipe for the set
04	cashier	the system to tell me the milk tea is sold out the moment I tap it	I can offer the customer something else before they pay
05	cashier	the POS menu to grey out items that have run out of materials	I do not have to keep track of what is left in my head
06	kitchen staff	the materials to go back to stock when I void an item I have not made	they can be sold to the next customer
07	owner with a kitchen display	the materials deducted from the ledger when the kitchen marks the item done	the stock figures match what the kitchen actually made

5. Functional requirements

#	Requirement	Status	URD ref
FR-001	How an item draws down stock is derived from exactly two things, with no separate mode switch. • The type of the item: stocked goods, prepared item, bundle, manufactured goods, consumable, service, entitlement. • The item's own track-stock flag: on or off. • A consumable is an item that physically exists but keeps no stock: it never touches inventory and never goes through a bill of materials. • Every combination of these two has a defined drawdown path; no combination is left open.	🔶	URD-BOM-001
FR-002	Stocked goods that track stock draw down on their own stock. • The item keeps its own stock row and sells one-for-one against it. • Such an item never goes through a bill of materials, even when one is attached to it.	🔶	URD-BOM-002
FR-003	A prepared item that tracks stock has no stock row of its own. • Selling one portion explodes the bill of materials and draws down the materials directly. • Inventory shows no stock figure for such an item. The only number that means anything is how many portions can still be made, computed from the materials.	🔶	URD-BOM-003
FR-004	A bundle has no stock at the parent level and no bill of materials of its own. • Tapping a bundle into the order explodes it into its component items right there. • Each component draws down stock by its own type and its own track-stock flag. • Any component that is a prepared item goes on to explode its own bill of materials.	🔶	URD-BOM-004
FR-005	Manufactured goods that track stock draw down on their own finished-goods stock. • The item keeps its own finished-goods stock row, and selling it at the counter draws down that row directly. • Its bill of materials only runs when a production order runs (see Production Order); it never explodes at the counter.	🔶	URD-BOM-005
FR-006	Services and entitlements never track stock. • The product edit screen does not let the track-stock flag be turned on for these two types. • An item that does not track stock never touches inventory however much it sells, whatever its type is.	🔶	URD-BOM-001
FR-007	Only prepared items and manufactured goods are allowed through a bill of materials. • If an item of any other type has a bill of materials attached, that BOM is ignored at sale time and no materials are drawn down. • This rule is enforced in the drawdown path itself, so it does not depend on whether somebody attached the wrong BOM.	🚧	URD-BOM-001 · URD-BOM-002
FR-008	A bill of materials is a component list with quantities for one portion of the finished item. • Each component line is a material or another item, with a quantity and a unit of measure. • A component line marked optional does not block the sale when it is short. • A bill of materials has three states: draft, active, retired. Only the active one explodes at sale time. • An item has exactly one active bill of materials at a time; activating a new one retires the old one automatically.	🔶	URD-BOM-013
FR-009	Materials are checked and reserved the moment the cashier taps the item into the order, not at payment. • With enough material the item drops into the cart and the matching portion of the materials moves to reserved right there. • When a material is short the item is refused right in the cart, naming the material that is short, while the customer has not paid yet. • Prepared items and bundles share this one reservation mechanism, at the same moment and with the same release path.	🚧	URD-BOM-006
FR-010	The allow-oversell flag is evaluated per material, not across the whole bill of materials. • A material with allow oversell on is still let through when its stock is short, and its stock goes negative. • Other materials in the same bill of materials that do not have the flag on are still blocked as normal.	🔶	URD-BOM-007
FR-011	The number of sellable portions of an item that goes through a bill of materials is computed from its materials. • For each material, divide its available stock by that material's quantity in the bill of materials. • The sellable portion count is the smallest of those results, rounded down. • Once that number hits 0 the item shows as sold out on the POS menu and can no longer be tapped into an order.	🚧	URD-BOM-008
FR-012	BOM explosion stops at every component that has stock of its own, and only continues through a component with no stock of its own. • A component line with stock of its own stops the explosion right there and draws down that component's own stock. This applies to raw materials, semi-finished items with stock tracking on, and manufactured goods with stock tracking on. • The system does not continue down to the materials that made that component, because those were already deducted at the production order. Continuing further is a double deduction. • It only continues further when that component has no stock of its own, meaning a prepared item. • The deciding question is "does this component have its own stock", not "does this component have a nested bill of materials". • The maximum explosion depth is 8; anything beyond that is refused at save time. • A bill of materials may not loop back to itself, directly or through an intermediate; a cycle is blocked at save time. • The reservation step at tap time and the ledger deduction step at item completion explode to the exact same depth, never to different ones.	🚧	URD-BOM-009
FR-013	By default materials leave the location for real the moment the order is paid. This path runs for every merchant, whether or not it has a kitchen display.	🚧	URD-BOM-010
FR-014	A merchant with a kitchen display can pick a different deduction moment. • Merchant configuration carries an option to move the ledger deduction to when the kitchen marks the item done. • With the option on, materials stay reserved after the customer pays and only leave the location when the kitchen marks the item done. • With the option off, the system falls back to deducting at payment.	🚧	URD-BOM-011
FR-015	When the kitchen voids an item before marking it done, the materials reserved for that item are released, available stock goes back up, and no material was ever deducted from the ledger.	🔶	URD-BOM-012
FR-016	Removing an item line from the order, or voiding the whole order before the ledger deduction, also releases every material reserved for it, with no extra action required and no popup.	🔶	URD-BOM-012 · URD-RSV-006
FR-017	Running out of a semi-finished item mid-shift sends its stock negative with a warning, never falling through to raw materials. • When a semi-finished item's stock hits 0 and the item keeps selling, its stock goes negative and the merchant gets a warning. The system does not block the sale. • The system must never automatically switch to deducting the materials used to make that semi-finished item. • That negative number is exactly the signal a merchant needs to know the kitchen cooked more without logging a production order, so it can be reconciled at close of day.	🚧	URD-BOM-014
FR-018	Changing a recipe quantity does not rewrite history. • Changing a bill of materials quantity means adding a new version with an effective date, never overwriting the old one. • The quantity used to draw down stock is stamped onto the document itself at the moment it happens, so an old document always reads back the exact quantity that was in effect at that time. • Changing a quantity today never changes the cost of orders already closed out before it.	🚧	URD-BOM-015

5.1 Acceptance criteria

• Set "Can of soda" as stocked goods, tracking stock, 10 cans on hand, then attach a bill of materials to it → sell 1 can → the item's own stock drops to 9 cans and no material in the BOM is drawn down.
• Set "Milk tea" as a prepared item, tracking stock, with a bill of materials of 50ml of milk per glass → open the stock screen and search for "Milk tea" → there is no stock row for milk tea at all; only the milk, tea and pearls have stock.
• Sell 1 glass of milk tea → the milk drops by exactly 50ml, and the tea and the pearls drop by exactly their BOM quantities.
• Set "Chicken rice set" as a bundle of 1 rice portion and 1 chicken portion, both stocked goods tracking stock → sell 1 set → the bundle has no stock row of its own; the rice drops by 1 and the chicken drops by 1.
• Set "Tamarind sauce" as manufactured goods tracking stock, with a bill of materials of tamarind and sugar → sell 1 jar at the counter → the jar stock drops by 1 and the tamarind and sugar stock stay unchanged (the BOM only runs for a production order).
• Open the edit screen of a service item → the track-stock box cannot be turned on; sell that item → no stock record changes.
• Set "Straw" as a consumable → sell 10 of them → there is no stock row for straws and no material is drawn down.
• Mark the pearls line in the milk tea bill of materials as an optional component, with pearls at 0 → the cashier taps "1 milk tea" → the item still drops into the cart normally, and the milk and tea are still reserved at their BOM quantities.
• Set the milk tea bill of materials back to draft → sell 1 glass → no material is reserved and no material is deducted.
• Activate a new bill of materials for milk tea → the old one is retired automatically; sell 1 glass → only the new version's quantities explode, the old one is no longer used.
• Milk is down to 30ml, the milk tea BOM needs 50ml, and milk does not have allow oversell on → the cashier taps "1 milk tea" → the system refuses right in the cart, reporting the milk shortage, before the customer pays.
• Same bill of materials, milk is fine but ice cubes have allow oversell on and ice stock is 0 → tap "1 milk tea" → the item drops into the cart normally, the ice stock goes negative, and nothing is blocked.
• Tap "1 milk tea" successfully → open the material stock screen → milk: on hand unchanged, reserved up by 50ml, available down by 50ml.
• Milk is at 200ml (BOM 50ml), tea at 12g (BOM 5g), pearls well in surplus → open the POS menu → milk tea shows 2 portions left (the smaller of 4 and 2).
• Pearls hit 0 with no allow oversell → open the POS menu → milk tea shows "sold out" and cannot be tapped into an order.
• "House-made pearls" is a semi-finished item with stock tracking on, currently at 2000g, with its own bill of materials of tapioca starch and sugar. The milk tea BOM calls for 30g of pearls → sell 1 glass → pearl stock drops to 1970g and the explosion stops there; tapioca starch and sugar stock stay unchanged, because they were already deducted when the batch of pearls was cooked.
• The same glass of milk tea, but "House-made pearls" is declared as a prepared item with no stock of its own → sell 1 glass → the explosion continues one more level, and the tapioca starch and sugar are drawn down at their BOM quantities.
• Broth is a semi-finished item with stock tracking on, at 47 litres, with bone stock at 15kg. The bowl-of-pho BOM calls for 200ml of broth → sell 1 bowl → broth stock drops to 46.8 litres, bone stock stays unchanged at 15kg.
• Same shift, keep selling until broth stock hits 0, then sell one more bowl → broth stock goes negative 200ml with a warning; bone stock stays unchanged, and the system never deducts bones to make up for it.
• Change the broth quantity on the bowl-of-pho recipe from 200ml to 220ml → reopen a pho order closed out yesterday → the old order still reads back a quantity of 200ml and its cost is unchanged.
• Write a bill of materials nested deeper than 8 levels, or one with a component that loops back to the item itself → hit save → the system refuses, reports the error right in the form, and the BOM is not saved.
• A merchant with no kitchen display, milk tea order paid → open the material stock screen → milk: on hand down by 50ml, reserved back to 0.
• A merchant with the deduct-at-kitchen-done option on, milk tea order paid → the milk is still reserved and on hand is unchanged; the kitchen marks the item done → on hand drops by 50ml and reserved goes back to 0.
• Same merchant, the kitchen voids the item instead of marking it done → the reserved materials are released, available goes back up, and on hand is unchanged.
• The cashier removes the milk tea line from the order before payment → every material reserved for that glass is released immediately, with no popup.

6. Non-functional requirements

Aspect	Requirement
Accuracy	BOM quantities are converted to the base unit before drawdown; the computation keeps 4 decimal places
No double drawdown	An item line is reserved once and deducted once, even if the sale event repeats; the second time produces no further stock movement
Performance	The multi-level BOM explosion at tap time loads the whole BOM branch in one pass, never one query per level
Limits	Maximum explosion depth 8; a cycle in a bill of materials is blocked at save time, not left until sale time
Concurrency	Two cashiers tapping the same item on two terminals at the same time cannot reserve more than the stock actually on hand
i18n	BOM names and descriptions are bilingual

7. UX & flows

The owner goes into Inventory, opens the Bill of Materials screen, picks the item and adds each component line with its quantity and unit. The item type and the track-stock flag are set on the product screen over in the catalog. The deduction moment is set once in merchant configuration. The cashier never sees any BOM screen: all the cashier sees is whether an item can still be sold or has run out.

8. Data & domain

Concept	Role
Bill of materials	The quantities that make one portion of a finished item; attached to an item or a semi-finished item; has a draft / active / retired state
Component line	A material or another item inside a bill of materials, with a quantity, a unit of measure and an optional flag
Item type	Stocked goods, prepared item, bundle, manufactured goods, consumable, service, entitlement; a consumable physically exists but keeps no stock
Track-stock flag	Whether the item touches inventory at all; combined with the item type it derives the drawdown path
BOM explosion	Drilling from the item being sold through its recipe, across multiple levels (up to 8), stopping at every component that has stock of its own
Sellable portion count	The smallest of the ratios (a material's available stock / its BOM quantity), rounded down
Deduction moment	Merchant-level configuration: at payment (default) or when the kitchen marks the item done

Conceptual level only - the full schema and invariants live in the inventory domain model.

9. Dependencies & assumptions

Depends on

#	Feature	What it depends on
01	MAT Materials	the components of a bill of materials are materials, each carrying its own track-stock flag and allow-oversell flag.
02	UOM Units of Measure & Conversion	whatever unit a BOM quantity is written in, it is converted to the base unit before stock is drawn down.
03	RSV Stock Reservation & Oversell Guard	reserving and releasing materials goes through the shared reservation mechanism.
04	STK Stock Items & Levels	the four stock numbers of each material are what the sufficiency check reads.
05	Product catalog	the item type and the track-stock flag are set there; Inventory only reads them.
06	Sale flow	tells Inventory when an item enters an order, when the order is paid, and when the kitchen marks an item done or voids it.

Assumptions

#	Assumption	What breaks if it is wrong
01	An item has exactly one active bill of materials at a time; changing the recipe means retiring the old one and activating a new one.	With two versions in force at once the system does not know which one to draw down against, and the same item deducts different amounts on two consecutive sales.
02	BOM quantities are fixed for one portion; they do not vary by item size or by add-on options.	A large glass takes more milk than a medium one, and with only one number in the recipe the milk stock drifts a little further every day, leaving the stock count to absorb the whole gap.
03	When a material has run out and does not have allow oversell on, blocking the sale is better than leaving the stock wrong.	If the merchant would rather sell than keep the book right, blocking in the cart is blocking revenue, and allow oversell should default to on rather than off.

10. Release plan & criteria

Aspect	Plan
Phase	P2 (Inventory v2) - see the feature URD catalog
Rollout	Every merchant; the item type matrix applies to the whole catalog, and the kitchen-based deduction option is opt-in per merchant
Migration	Items that carry a bill of materials but are not prepared items or manufactured goods have to be reviewed and re-typed before the matrix takes effect
Release criteria	Selling a prepared item draws down the right components at the stopping level (a component with stock of its own is drawn down on that stock, with no drilling below it); running out of a material blocks it right in the cart; a merchant with no kitchen display still deducts in full after payment; no material is left stuck in reserved after its order closes
Monitoring	Item refusals in the cart for material shortages, stuck reserved materials per merchant, material stock variance across stock count periods

References

• URD: Bill of Materials · Materials · Stock Reservation & Oversell Guard
• Related: Production Order · Units of Measure & Conversion · Stock Items & Levels
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & open questions

#	Risk / question	Mitigation / status
01	Changing an item's type while it still has stock (stocked goods to prepared item, say) leaves the item's old stock meaningless	Handling rule: sell the old stock down first, then change the type; the system warns while the item still has stock
02	If the reservation step and the deduction step explode to different depths, the amount reserved and the amount deducted diverge	Both steps share one explosion to the same depth (FR-012)
03	A merchant with no kitchen display but a deduction moment anchored on the kitchen would leave materials reserved forever	The default deducts at payment, independent of any device (FR-013); the kitchen-based option is opt-in
04	A bundle inside a bundle inside a prepared item, several levels deep, makes tapping an item into the order visibly slow on the POS	Load the whole branch in one pass, cap the depth (NFR Performance)
05	A quantity written in a fractional unit (0.05 litres of milk, say) rounds wrong when multiplied by a large portion count	Convert to the base unit and keep 4 decimal places throughout
06	Whether a prepared item should be able to show a "virtual" stock figure in inventory reports	Open: show the sellable portion count as a derived indicator, or show nothing at all

Frequently asked questions

#	Question	Answer
01	Why is there no separate flag for choosing the drawdown mode?	Because the item type and the track-stock flag are enough. A third flag would produce contradictory combinations like "stocked goods but drawn down through a recipe" that nobody could explain to an owner, and every combination would spawn another handling branch.
02	Does a prepared item have stock?	Not of its own. The only number that means anything is how many portions can still be made, derived from the materials. If you want the item to carry its own stock, it is manufactured goods, not a prepared item.
03	Does a bundle have its own bill of materials?	No. A bundle explodes into its components, and any component with a bill of materials explodes its own. Writing a separate BOM for the bundle would just be writing it twice.
04	Why reserve the materials at tap time instead of waiting for payment?	Because the moment before the customer pays is the only moment things can still be fixed. Finding out the milk is gone after the money is in the till leaves nothing but an apology and a refund.
05	My merchant has no kitchen display - can I still use a bill of materials?	Yes. The materials are deducted the moment the order is paid. The kitchen-based deduction option is only for merchants that run a kitchen display.
06	How deep can a bill of materials nest?	8 levels at most. A bill of materials also may not loop back to itself, directly or through an intermediate; the system blocks that at save time.
07	A material has run out and I still want to sell - what then?	Turn allow oversell on for that specific material (ice cubes, straws). Other materials in the same bill of materials are still blocked as normal.
08	Does selling a bowl of pho deduct bones?	No. Broth is a semi-finished item with stock of its own, so the explosion stops at the broth. The bones were already deducted once, at the production order that cooked the pot of broth. Deducting them again when the pho sells would deduct the same goods twice.