Orders Module

Status: Designed — build pending. The design described here is complete and under team review; it is not yet built into the runtime. It is the target for the Orders with Lifecycle project. The order capabilities that exist in the live system today are the client-side purchase-order sheet described in Purchase Orders and Order Lifecycle; see Relationship to the current purchase order for what changes.

Purpose

An Order is the durable agreement document a buyer builds to obtain materials from a single supplier. It gathers approved production requests into one commitment, is sent to the supplier and — optionally — acknowledged by them, and is closed out as material arrives, possibly across several deliveries. The order is a lasting business record: every change to it is an explicit action by a named person, recorded with its full history, so the order is its own audit trail. Nothing about an order changes on its own.

The module deliberately names its central concept Order, not Purchase Order: the same structure is designed to serve other single-supplier agreement documents in future (for example, an outbound fulfillment order), so the vocabulary stays general.

Main entities

An order has a header and one or more lines. The header carries the order’s status and the chosen supplier; each line records what is being ordered, how much, the supplier’s answer, how much has been received, and which production requests the line services.

In plain terms:

• Order — the agreement document. It has an order number, a status, and the supplier it commits to. The supplier can be a fully linked business affiliate acting as a vendor, or just a name typed in (an informal “supermarket” supplier is allowed). While the order is a draft the buyer can choose the supplier, override contact details for this order only, and reset those overrides; at submission the supplier details are frozen.
• Order line — one thing being ordered. A line names an item and a requested quantity, and it may carry the supplier’s confirmation (their answer) and a running received quantity. A line can also be free-form — a documentary line with no item, which is not tracked for receipts. A line services zero or more production requests (demand): these tell the system which shop-floor needs this line will satisfy.
• Supplier — a reference to a business affiliate in the Business Affiliate reference data, acting in the Vendor role.

Lifecycle

An order moves through four stored states. Draft is where the buyer composes it; Submitted is the standing state once it has been sent to the supplier; Closed and Canceled are final. Two further labels — Confirmed and Receiving — are computed views shown to the user, not stored states: an order reads as Confirmed once every live line has an answer from the supplier (including a waived answer), and as Receiving once any line has received material. Receiving takes precedence over Confirmed.

Cancel is deliberately available only while the order is a draft. Once an order has been sent to a supplier, canceling it would retract a commitment made to an outside party, so it is not a casually available action; if that path is ever needed it will be designed on its own against concrete requirements. Closing an order requires every open line to have been closed first — a line can be “closed short” (closed while some quantity is still outstanding), but only by a deliberate act, never automatically.

Operations

The actions users (and neighboring modules) can perform on an order. Each is an explicit, recorded act; an action that is not allowed is rejected with a specific, typed reason the user can act on.

Action	What it does	When it is allowed
Create	Starts a new order in Draft, with an initial supplier (a name is enough).	Always.
Choose / override / reset supplier	Sets or adjusts the supplier for this order; reset discards the per-order overrides.	Draft only.
Add line	Adds a line — from a production request in the queue, from an item, or free-form. Adding from a bare item creates the matching production request on the fly.	Draft only; the production request must be approved, waiting in the queue, and not already held by another live line.
Edit line quantity	Changes a line’s requested quantity. (The item on a line is fixed; to change it, remove and re-add.)	Draft only; line still open.
Attach / detach production request	Adjusts which production requests a line services.	Draft only; same eligibility rules as adding a line.
Remove line	Removes a line while composing; its production requests return to the queue.	Draft only.
Submit	Commits the order: freezes structure and supplier, records the supplier snapshot, and marks every serviced production request as being in production.	Draft only; at least one line; supplier named; every serviced request ready to start.
Record acknowledgment	Records the supplier’s answer on a line — accepted, changed, backordered, rejected, substituted, or waived (acknowledged without an explicit answer).	Order submitted or later; line still open.
Record receipt	Adds received material to a line as it arrives. Received amounts accumulate; they are never overwritten.	Order open; line still open; line is not free-form.
Close line	Marks a line done, by the buyer’s decree — closing it short if quantity remains.	Order open; line still open.
Close order	Marks the whole order done.	Order submitted; every live line closed.
Cancel	Abandons the order while composing.	Draft only.
Annotate	Adds a note to the order or a line — also how out-of-system revisions are recorded.	Any state.
Delete	Retires a finished order.	Order is closed or canceled.

Guarantees

The design makes these promises in plain language:

• No double-ordering. A production request is serviced by at most one open order line at a time, so the same shop-floor need is never ordered twice at once.
• No silent edits after submission. Once an order is submitted, its lines and its supplier are frozen; only answers, receipts, notes, and closure can still be recorded.
• Received amounts are real and additive. Received quantity is accumulated from actual receiving events, never overwritten; the open quantity a user sees is computed from confirmed-or-requested minus received, not stored. Over-receipt is allowed and simply shows as a negative open amount.
• Receipts reconcile themselves. As material is received against the production requests an order services, the order’s received amounts update to match. If a receipt notification is ever missed, the system repairs the figure on its own — it does not silently drift.
• Every change is accountable. Each action is an explicit act by a named party, kept with its full history; the order record is the audit trail.
• Refusals are specific. An action that is not currently allowed is rejected with a specific, typed reason (for example, “the order is frozen” or “that production request is already held”), not a generic error.

How Orders relates to its neighbors

Orders sit at the top of a short chain. An order services production requests (the Demand module), which in turn collate signals from the kanban replenishment loop (Kanban Cards). Each module depends only on the one below it, and each is ignorant of the ones above: demand knows nothing about orders, and kanban knows nothing about demand. Orders also reference items (Item) and the supplier (Business Affiliate). Receiving — an upcoming capability — will depend on Orders, never the other way around.

Scope and non-goals

This design covers the behavior of an order — its structure, its lifecycle, and the rules that govern it. Several things today’s purchase order carries are intentionally outside that scope: some are parked for later, and some are handled at runtime rather than by the design.

Deliberately left out (retained as data or parked for future design):

• Money and costing. Unit costs, line costs, order totals, taxes, and currency are not part of this design. Prices and totals are runtime data; how the order moves through its lifecycle does not depend on them.
• Rich header details. Delivery address, procurement and sales contacts, payment and shipping terms, terms and conditions, and accounting references are kept as order data but are not part of the behavioral design — they travel with the order and its supplier snapshot without changing its lifecycle.
• Scheduling. Per-line delivery dates and expedite flags are not modeled; a need for several delivery dates is expressed as several lines.
• How the order reaches the supplier. The transmission channel — online, e-mail, or phone — is a runtime concern, not part of the design.
• Creation shortcuts. Building an order from a selection of cards, from a list of items, from a copy of another order, or from an imported file are conveniences layered on the basic “create an order, add lines” actions, not separate concepts in the design.
• Request-for-quote, kits, blanket/release agreements, and vendor-managed inventory. All parked for future design.

A few behaviors of today’s purchase order are deliberately changed or dropped (each is a decision for team review):

• Canceling is limited to drafts. Today an order can be canceled after submission; this design allows cancel only while the order is a draft (see Lifecycle). Canceling a commitment already sent to a supplier is left for explicit future design.
• Partial and over-receipt are always allowed. Today an order carries an “allow partial” switch; this design always permits receiving more or less than ordered, showing the difference as a computed open amount.
• Supplier compatibility is not enforced while composing. Today, ordering a set of cards requires them to share a compatible supplier; this design chooses the supplier at the order level and does not restrict which approved production requests a line may service.

Relationship to the current purchase order

The live system today has a client-side purchase-order sheet, documented in Purchase Orders and Order Lifecycle. The redesigned Order described on this page supersedes that model where the two disagree:

• Fewer stored states, with computed views. The current sheet uses a longer status list (NEW, SUBMITTED, IN_PROCESS, PARTIALLY_RECEIVED, RECEIVED, CLOSED, ARCHIVED, CANCELLED). The redesign stores only Draft / Submitted / Closed / Canceled and derives Confirmed and Receiving as views rather than storing them.
• Received amounts are event-driven, not header fields. Today the sheet tracks receiving state on the order; the redesign accrues received quantity on each line from actual receiving events and computes the open amount.
• Cancel is draft-only. The current sheet allows canceling a submitted order; the redesign restricts cancel to drafts and parks post-submission cancellation for explicit future design.
• The order becomes a durable server-side entity. The current sheet is client-side only; the redesign makes the order a lasting record, which is net-new frontend and backend work with no data to migrate.

Those legacy pages remain the accurate description of what ships today until the Orders with Lifecycle project is built.