FLOW-0001 — The Pull-Replenishment Round Trip

This is the flagship scenario — the round trip the product exists to run. Stock runs down at a station, and without anyone tracking state by hand the system carries the signal all the way out to a supplier and the goods all the way back to the point of use: the card signals, demand collates, a buyer commits an order, the dock receives and accepts the delivery, inventory is born and distributed to the waiting card, and the restocked bin re-arms replenishment for the next lap.

Use cases traversed

This flow is a path across use cases, in order. Identifiers are the immutable prefix form defined in the naming convention; a flow is not a level-4 scenario.

Domains crossed: Resources, Operations, Procurement, Receiving.

Step	Use case	What happens
1	RES::KC::0004	A card is consumed and signals
2	RES::KC::0005	The card enters the order queue
3	OPS::DEM::0001	Demand is collated into a production request
4	PRO::OQ::0007	An order is created from the queue
5	PRO::PO::0004	The order is submitted and freezes
6	PRO::RCV::0001	The shipment is received
7	OPS::DEM::0002	The production request completes

The business value is the absence of the alternatives: no stockouts from unnoticed empty bins, no spreadsheet shadow systems, no re-keying between ordering, receiving, and inventory records — and a permanent, self-consistent record of every step.

Actors and domains

The actors are personas; each leg names the ones on stage:

• Sam Scansworth — shop floor. Triggers replenishment by consuming supplies and scanning the card at the reorder point.
• David Dealsworth — procurement. Composes the order from the demand queue and commits it to the supplier.
• Vera Vendorson — the external supplier. Receives the committed order and ships the goods; not a platform user.
• Keisha Clerkson — receiving. Captures the delivery at the dock, accepts and rejects, and returns the card to its shelf.
• Irene Itemsworth — inventory manager; appears in the withdrawn-card alternate.

The domains carry the system’s side of each leg. Throughout this page every diagram uses one background color per domain — receiving (orange), procurement (green), operations (yellow), resources (blue), reference-data (lavender) — and orders domains and modules left to right by dependency: clients to the left of the servers whose operations they invoke. A solid arrow is an operation invoked on the participant it points at, following the module dependency direction (left to right); a dashed arrow is a notification flowing against it, right to left (see Everything is Observable).

The round trip at domain level

The whole round trip in one pass, with each participant either an actor or a domain. The four legs that follow zoom into each segment at module granularity.

Leg 1 — The card signals and demand collates

Sam empties the front bin and scans the card at the reorder point. That starts a new card cycle — one lap of the card’s loop, the configured route it travels — and the cycle’s signal becomes eligible for collation into a demand item: the collated “intent to produce” that the rest of the trip services. Which eligible signals group into which demand item is the composing caller’s business decision; the Demand module enforces only the integrity half — eligibility, no double-holding, and the lifecycle rules.

The card cycle’s full lap machine — including the states the cycle moves through while the rest of this scenario runs — is the state diagram on the Kanban Cards page. The demand item’s own machine (Open → Released → In production → Complete) is on the Demand page.

Leg 2 — The buyer composes and commits the order

David reviews the demand queue and composes an order. While the order is a Draft he can shape it freely: add lines from waiting demand items, adjust quantities, choose or override the supplier. Every reference the order takes — the vendor, each line’s item, the assignee — is pinned to that record’s current version, so the order permanently shows what it was agreed under (the Reference-Data Module Pattern).

Submit is the commitment: it freezes the order’s structure, supplier, header details, and assignee on their pinned versions, and marks every serviced demand item as being in production. The floor for submission is real: the supplier must be linked to a vendor record (a name alone can compose a draft but never a commitment) and that vendor must not be retired.

The order and order-line machines — including the computed Confirmed and Receiving views over Submitted — are on the Orders page.

Leg 3 — The delivery is received, inventory is born, distribution reaches the card

Vera ships. Keisha creates a receiver at the dock and adds lines from the order — a line created from an order line is born already attributed to it, with the expected amount frozen from the order line (which receiving reads and never writes). Receive is the freeze: in one act the line’s accepted and rejected counts, the rejection reason, the captured facts, and the attribution actuals are written and become the permanent record — and the accepted goods are born as an inventory pool located at the dock.

Distribution then moves the born inventory onward against the frozen record: the delivery is recorded against the demand item, the material lands in its holding pool, and the waiting card’s cycle loads it. The delivery announcement is what keeps the order honest — Orders listens and updates how much has been received against each line, self-healing if a notification was missed. (The announcement’s emission is designed but not yet wired up in the running system — see the note on the Demand page.)

The receiver and receiving-line machines — capture, the freeze, and distribution’s completion gate — are on the Receiving page; the pool’s custody and condition machinery is on the Inventory Items page.

Leg 4 — The card returns and replenishment re-arms

The trip’s last meters are physical. Keisha restocks the shelf and returns the card to its position; Sam draws from the restocked bin; and when the front bin empties again the same card re-triggers demand — the next lap on the same card, with no setup, no reminder, and no one keeping a list.

The cycle’s rollover — one lap ending exactly where the next begins — is part of the lap machine on the Kanban Cards page.

Alternate paths

Three departures from the happy path stay inside this scenario’s frame. Deeper treatments of receiving discrepancies and replenishment self-healing belong to their own scenarios in the catalog.

The draft order is canceled

While the order is still a Draft, David can abandon it. Cancel is final for the order — and free for everything else: every attached demand item returns to the queue exactly as it was, eligible for the next order, with no cleanup required. Cancel is deliberately unavailable once the order is Submitted: that would retract a commitment made to an outside party (see the Orders lifecycle).

Part of the delivery is rejected at the dock

Keisha counts what actually arrived. The freeze records the accepted and the rejected counts — with the reason — as one permanent record, and only the accepted goods are born as inventory. The rejected count never becomes stock; it becomes evidence for the conversation with the supplier.

The card is withdrawn mid-lap

Irene takes a card out of circulation while its lap is still running — the item is being discontinued, or the card is damaged and being replaced. Withdraw ends the lap from any live state, and replenishment reconciles itself: Demand hears that the card’s trip ended and detaches its signal from whatever demand item held it; a demand item left empty with nothing else expected cancels itself. Nothing is orphaned, and no one has to remember to clean up.

The reconciliation the ref fragment points at branches on what the ended trip leaves behind:

The same reconciliation runs on the ordinary rollover — a card starting its next lap ends the previous trip the same way — which is what makes replenishment self-healing rather than exception-driven; see the listener notes on the Demand page.

Where the behavior is specified

Every step above is documented, with its state machine and guarantees, on the module pages:

• Kanban Cards — the card, the cycle, and the lap machine.
• Demand — demand items, collation, production deliveries, and the trip-ended reconciliation.
• Orders — composition, the Submit freeze, pins, cancel, and received amounts.
• Receiving — capture, the freeze, attribution, and distribution.
• Inventory Items — pool birth, custody, and condition.
• Reference-Data Module Pattern — the version pins and retirement gates the trip relies on.