Design: Orders with Lifecycle

Overview

An order is the durable agreement document at the boundary of a supplying station. It collates released production demand into a single-supplier commitment, is negotiated with the supplier through submission and (possibly waived) acknowledgment, and is closed as material arrives — possibly across several deliveries. It is a lasting record: history is the audit trail, received and open quantities are maintained-and-computed readings, and every change is an explicit act by a named party. Nothing transitions on its own.

This page is the reviewed design. The plain-language module reference lives at Orders module; the decisions behind the design are in Decisions.

Decision summary

#	Decision	Chosen approach
DEC-01	Where do holds on demand live?	Order-side only — the order line holds the production request; demand stays unaware.
DEC-02	Can a submitted order be canceled?	No — cancel is draft-only; post-submission cancellation is parked.
DEC-03	How are received amounts represented?	Received quantity is stored and accrued from events; open quantity is computed.
DEC-04	When does the supplier freeze?	At submission — a snapshot is recorded and no further supplier changes are accepted.
DEC-05	What are the stored states?	Draft, Submitted, Closed, Canceled — with Confirmed and Receiving as computed views.

Full rationale in Decisions.

Structure

An order has a header and one or more lines. The header carries the stored status and the supplier binding; each line records what is ordered, the requested quantity, the supplier’s answer, the received quantity, and the production requests it services. The composition is carried on the line (a line names its order); the order’s set of lines is a derived reading.

Lifecycle

An order is stored in one of four states. Confirmed and Receiving are computed views over Submitted, not stored transitions: an order reads as Confirmed once every live line has an answer (including waived), and as Receiving once any line has received material — Receiving takes precedence.

The demand relationship

An order line services zero or more production requests from the Demand module. The dependency runs one way: the order line carries the reference; demand does not know which order (if any) holds it (DEC-01). Whether a request is “spoken for” is answered by asking the order side, not the demand side.

• Attaching a production request to a line commits nothing on the demand side; the line simply requires the request to be approved, waiting in the queue, and not already held by another live line (no double-ordering).
• Submitting the order marks every serviced request as being in production — the commitment to buy is the start of the run for a supplying station. This cascades down the dependency ladder — Order → Demand → Kanban — each module calling only the module beneath it.
• Holds die with the order. Because “which line holds this request” requires the parent order to be live, canceling or closing an order returns its serviced requests to the queue with no line-by-line cleanup.

Submitting an order

If the submit is interrupted between steps, the situation is recoverable: requests already started are a legal in-between state, and retrying the submit converges. Nothing is left half-committed in a way the system cannot reconcile.

Received-quantity reconciliation

Received quantity is stored on each line and accrued from events (DEC-03): only actual production/receipt events move it, by adding to it — never by overwriting. The open quantity a user sees is computed as confirmed-or-requested minus received, and may go negative on over-receipt (over-receipt is admissible and advisory).

Module boundaries

• Order → Demand → Kanban is the dependency ladder; each module depends only on the one beneath it and is unaware of the ones above.
• Receiving depends on Order, never the reverse. The upcoming receiving capability will resolve an order’s line-to-request mapping and drive the demand-side events; the order edge only listens.
• A line without an item is free-form — documentary only: no demand pairing and no received tracking; its receipt story is closure-by-act plus notes.

Out of scope

• The receiving clerk’s workflow (upcoming; this design provides only the reconciliation groundwork).
• Money and costing, rich header attributes, scheduling, amendment protocol, agreement/release layer — see the module’s Scope and non-goals.

References

• Goal
• Decisions
• Orders module
• Demand module