Supply chain

Supply chain covers how stock arrives and leaves other than by a sale: suppliers and what they sell, purchase orders, receiving deliveries, supplier bills read from a photo, waste and yield, transfers between locations, and a daily low-stock digest. Every quantity it moves goes through Inventory, which it needs. Orders to suppliers and alerts go out through Outbox. With POS on, staff receive deliveries at the register. Supply chain doesn't pay suppliers: a confirmed bill records what arrived and what it cost, and paying it happens outside the app.

What it handlesCopy Anchor Link

• Sending a purchase order. Sending marks the order sent and queues one message per supplier channel (an email with the order as a PDF, a LINE message) in the same write. An empty draft can't be sent. Ten orders raised at once at one location are numbered 0001 to 0010 with no gap or repeat, and another location starts its own count. Tested: "Supply: purchase orders" Tested: "Supply: draft purchase orders"
• Deliveries received twice, or more than ordered. A receipt retried with the same key adds stock once, even when both tries arrive together. A second delivery that would take a line past what was ordered is refused. Tested: "Supply: receiving" Tested: "Supply: sequential over-receipt"
• A crash halfway through receiving. If the server stops after a delivery is recorded but before its stock lands, the next time anyone opens the order the stock reaches the shelf, once. A bill left half done is finished the same way. A daily sweep finishes transfers and anything else nobody opened. Tested: "Supply: receiving through a crash" Tested: "Supply: bills through a crash" Tested: "Supply: the daily recovery sweep"
• Reading a supplier's bill from a photo. Each printed line is matched to the closest stock item, and a line with no match stays unmatched rather than guessed. A field the photo didn't show clearly stays empty and blocks confirming until staff fill it in. A bill that turns up after a delivery was counted without paperwork attaches to that delivery without counting the stock again. Reading a bill again more carefully keeps what staff already changed. Tested: "Supply: invoice scan" Tested: "Supply: read again carefully"
• Waste and yield costed from real batches. Waste is taken from the oldest batch first and costed from the batches it emptied. A yield turns an input into an output batch that carries the input's cost. A yield that would use more input than there is writes nothing, and a form submitted twice produces once. Tested: "Supply: waste and yield"
• Branch managers stay in their branch. A manager tied to one branch can't raise an order, receive a delivery, confirm a bill or write off stock for another branch by naming it in a request, or move stock between two branches that aren't theirs. That branch's own manager can. Tested: "Supply: purchase order branch scope" Tested: "Supply: receiving branch scope" Tested: "Supply: invoice by-id scope" Tested: "Supply: transfer branch scope" Tested: "Supply: waste and yield branch scope"
• One digest a day. Each recipient gets one low-stock and expiring-stock digest per local business day, by email and LINE, even when the schedule runs again. Item names are escaped in the email. Staff without supply:read can't read the low-stock list. Tested: "Supply: alerts"
• Receiving at the register. With POS on, kitchen and stock-room staff count deliveries at the register with their PIN. They see quantities, and every price shows as zero; an owner sees the prices. Front-of-house staff, or a request with no sign-in, are refused. A delivery with no bill lands at the supplier's last price (or the item's current cost when there is none) and waits in the manager's queue for its bill. Tested: "Supply + POS: register receiving" Tested: "Supply + POS: register receiving without a bill"

What you build on topCopy Anchor Link

• Modules alongside. Inventory is required. Switch on POS to receive deliveries at the register, and Storefront so transfers and write-offs account for stock an online checkout is holding.
• The register sign-in. The supply-chain.register-auth slot wraps the register's Receive page with whatever signs staff in there. POS fills it with its staff PIN session, so Supply chain never imports POS; without POS the page keeps the admin sign-in. See Extend a Module.
• Bill photos. Photos of supplier bills are kept in the optional media file storage connected to the app.
• Who can use it. Manager starts with supply:read and supply:write, and Viewer with supply:read. Grant them to other roles after the Module is installed.
• Automatic reordering. Replenishment can draft purchase orders for low stock daily or weekly. It's off until switched on in settings.
• Your words. Rename "Purchasing" or "Suppliers" with an override.
• In code. Your coding agent imports Supply chain only through its public API: index.ts and server/index.ts in apps/web/src/modules/supply-chain/. See Build on a Module.

LimitsCopy Anchor Link

• Supply chain doesn't track payments to suppliers. A bill goes from pending to confirmed or received; there's no paid state.
• Replenishment only drafts orders. A person reviews and sends each one.
• Low-stock alerts are a daily digest sent from one schedule at 07:00 UTC, not an instant message when an item drops below its level.
• Opening a purchase order or a bill can move stock, because it finishes a receipt a crash left half done. Don't cache or prefetch those reads in your app.

FactsCopy Anchor Link

• Kind: feature Module, can be switched on and off
• Needs: Audit log, Branches, Formatting, i18n, Identity, Infra, Inventory, Outbox, Standard UI
• Needed by: Nothing
• Adds to these when they're on: POS, Storefront
• Added to by: POS
• Off by default for these business types: Spa, Clothing, Tour operator, Gym, Online classes, Car hire, Snack store

Pages

Where	Path
Admin	/admin/supply
Register	/register/receive

Permissions

Admin holds every key. The other roles listed hold it when the app first gets the Module; after that, roles are yours to change under Settings → Roles & Permissions.

Permission	What it allows	Organization roles that start with it
admin-panel:write	Full compatibility access to all module administration, including POS, catalog, storefront, and CRM staff tools.	Admin
supply:read	View suppliers, purchase orders, invoices, waste, transfers, and alert settings.	Admin, Manager, Viewer
supply:write	Create and update suppliers, purchase orders, receiving, waste, yield, transfers, and alerts.	Admin, Manager

Data

• Tables: supply_supplier, supply_purchase_order, supply_purchase_order_line, supply_supplier_invoice, supply_waste_record, supply_waste_settings, supply_yield_record, supply_transfer_order, supply_transfer_order_line, supply_alert_setting, supply_replenishment_setting, supply_replenishment_run, supply_event, supply_po_sequence, supply_item_supplier, supply_item_mapping, supply_waste_document, supply_waste_document_row
• File storage media: optional, shared across the organization

Slots

Places other Modules and your app code can add to. See Extend a Module.

• supply-chain.register-auth

Tested workflows

• Supply: suppliers
• Supply: supplier spreadsheet import
• Supply: purchase orders
• Supply: draft purchase orders
• Supply: receiving
• Supply: waste and yield
• Supply: atomic waste evidence
• Supply: transfers
• Supply: alerts
• Supply: public boundary
• Supply: invoices
• Supply: invoice scan
• Supply: read again carefully
• Supply: item mapping
• Supply: item mapping and waiting deliveries are branch-narrowed
• Supply: attaching a scanned bill is branch-bound
• Supply: a late bill's quantities
• Supply: endpoint auth
• Supply: invoice by-id scope
• Supply: purchase order branch scope
• Supply: receiving branch scope
• Supply: transfer branch scope
• Supply: waste and yield branch scope
• Supply: replenishment
• Supply: waste batches
• Supply: draft transfers
• Supply: draft invoices
• Supply: purchasing on the inventory engine
• Supply: purchasing without POS
• Supply: receiving through a crash
• Supply: bills through a crash
• Supply: the daily recovery sweep
• Supply: sequential over-receipt
• Purchasing on the admin home
• Purchase orders in the admin search
• Supply + POS: endpoint congruence (with POS on)
• Supply + POS: register receiving (with POS on)
• Supply + POS: register branch scope (with POS on)
• Supply + POS: register receiving without a bill (with POS on)
• Supply: waste documents (with POS on)
• Supply: waste month (with POS on)
• Supply: moving an expired batch (with Storefront on)
• Supply: writing off held stock (with Storefront on)
• Supply: purchasing for the online shop (with Storefront on)