Demand Module

Status: Built — design convergence in progress. Operations wires the Demand service and its demand-item API, including production-delivery operations. The functional design below is the target for that implementation; the data model describes its stored shape and API surface.

What the runtime actually holds — tables, DTOs, cross-module references and API surface as they exist today — is Demand: Data Model. Where this page describes design ahead of the build, that page is the one that says what is stored.

Purpose

A demand item — the Demand module’s central concept — is one collated intent to produce a quantity of an item at a particular station (what the shop floor would call a production request). It is the collation layer between two granularities: individual kanban cards each signal a small, card-sized need, while production and procurement happen in aggregate. A demand item gathers many card signals (and direct, card-less demand) into one production task. Downstream, Orders service demand items; upstream, the kanban loop stays unaware of demand — it just emits signals.

Collation is the caller’s decision. Which eligible card signals go into which demand item — or wait on their own — is a business choice made by whoever composes the demand item. The module owns only the integrity half: eligibility, no double-holding, and the lifecycle rules.

Context

Demand is the collation layer of the domain map: two modules build on it, and it builds on four. Clients sit to the left of the servers they depend on; every arrow is a dependency the client calls, and together they form a DAG.

What this module consumes:

• Kanban Cards — the card signals a demand item collates; the commit gates read the card’s cycle so a signal is never double-held and a cycle is never outrun.
• Inventory Items — the holding pool where a demand item accumulates produced materials during its run.
• Processing Network — the station a demand item is made at (part of its identity).
• Item — what a demand item produces; creating a direct demand item reads the item’s current version at the gate.

What its clients consume from it:

• Orders — order lines service demand items waiting in the queue; an order’s Submit starts them, and demand’s accrual announcements keep the order’s received amounts honest.
• Receiving — as received material distributes to the shop floor, the caller records production deliveries against the demand item.

Main entities

• Demand item — identity is what is produced (the item) and where (the station). It carries the intended quantity, the card signals it has collated, and a holding pool where produced materials accumulate during the run.
• Production delivery — one recorded increment of produced material against a demand item: who delivered how much, when, into the holding pool. Deliveries are the granular truth the demand item’s produced total is derived from, and the record other modules (Orders’ received amounts, Receiving’s distribution) reconcile against.
• It references card signals from the Kanban Cards module and a holding pool from the Inventory Item module.

Functional decomposition

The module is one service with two endpoints — composing and running demand items, and the delivery-recording surface its distribution callers use.

• DemandItem service — owns the demand items and their deliveries. It provides the Demand items API (create, collate and release, start production, distribute, complete — the Operations table) and the Production deliveries API (record a delivery of produced material against a demand item in production — the endpoint receiving’s distribution and the station’s own reporting call; each delivery lands in the demand item’s holding pool and feeds the accrual announcement).

Lifecycle

Demand item

A demand item is composed while Open, frozen and handed to the station at Released, executed while In production (materials are produced in increments and distributed to the waiting cards), and finished at Complete. It can be abandoned only while still Open.

Production delivery

A production delivery’s content is immutable from the moment it is written, and its lifecycle has exactly one transition — a terminal revoke:

• Content never changes. Who delivered how much, when, into which demand item’s holding pool — fixed at creation. Corrections are revoke + recreate, never edits: reversing-entry semantics, so the audit trail is complete by construction.
• A revoked delivery contributes nothing — and stays forever. Revoking reverses the delivery’s contribution to the demand item’s produced total in the same act, and the record remains readable as the evidence of what was reversed.
• Only while the run lives. Deliveries can be recorded only against a demand item In production; that machine bounds the delivery’s writable window.
• The reconciliation anchor. The demand item’s produced total, the order’s received amounts, and receiving’s distribution ledger are all derived from, or reconciled against, the delivery records — which is why corrections reverse rather than rewrite.

Notifications

Every action recorded against a demand item is observable to the rest of the system — see how modules stay in sync. Two notifications carry business meaning beyond that generic channel.

What this module announces

• When a production delivery is recorded against a demand item, the module announces it. Orders listens, for any demand item attached to one of its lines, and updates how much has been received against that line. Both notifications are emitted after the commit, and Orders subscribes to them when it starts.
• When a production delivery is revoked, the module announces that too — a compensating decrement, not a fresh amount. Orders posts it as a reversal against the same line, with the same delivery-id idempotency discipline as the creation notification; once the order has closed, Orders refuses the reversal and alarms, because a receipt behind a closed order is credit-note territory — a human financial process, not an automatic one.

What this module listens for

• When a kanban card is withdrawn, Kanban Cards announces it and this module detaches that card’s signal from whatever demand item it was collated into. The other way a trip ends — the next lap beginning through the ordinary rollover — is designed to announce the same way and is not yet built, so today a rollover closure leaves the signal attached until something else detaches it. If that leaves the demand item both empty and with nothing else expected, the demand item cancels itself; see Scenarios below.

Scenarios

Three moments show the demand item lifecycle end to end. The caller in these diagrams is whoever is driving the workflow — an operator, a shop-floor screen, or an orchestrating service.

Two shop-floor signals collate into one demand item, which is handed off to the station once composing is done.

A withdrawal reconciles itself: when a collated card leaves its trip early, the demand item notices and lets it go — and if that was the only thing it was waiting on, the demand item closes itself out too.

A production run can settle in a single delivery: recorded into the demand item’s holding pool as a ProductionDelivery — the reconciliation record Orders and Receiving depend on — then distributed straight out to the one card still waiting on it, so the pool never accumulates anything.

These scenarios are verified against the formal model.

Operations

Action	What it does	When it is allowed
Create	Starts a demand item — empty, or from its first card signal. Creating a direct demand item for a retired item is refused (that create is the person’s own choice of target); a demand item created by a card’s cycle is not re-gated (the signal comes from an existing card’s cycle, not from a person’s new choice of target).	Any time.
Add / remove signal	Collates a card signal into the demand item, or returns it to the queue.	While Open.
Adjust quantity	Sets the intended total.	While Open.
Release	Hands the demand item to the station and freezes the intent.	From Open.
Reopen	Takes back a release to compose again.	From Released.
Start production	Begins the production run.	From Released.
Record a delivery	Records produced materials into the holding pool.	While In production.
Revoke a delivery	Reverses a recorded delivery — a compensating decrement to the demand item’s produced total, announced so Orders can reverse the line’s received amount.	While the delivery exists (revoke + recreate is the correction path); Orders itself refuses the compensating decrement, and alarms, once the order has closed.
Distribute	Allocates produced materials to the waiting card signals.	While In production.
Complete	Declares the run done (the result may differ from the intent).	While In production.
Cancel	Abandons the demand item before it is released.	From Open.
Delete	Retires a finished request.	When Complete or Canceled.

Guarantees

• A card signal is held by at most one live demand item at a time — no signal is produced twice at once.
• Collation is caller policy; integrity is the module’s. The module decides eligibility and prevents double-holding, but does not dictate which signals group together.
• Released intent is frozen. Once a demand item is handed to the station, its intended quantity no longer changes.
• Production accrues in increments. Materials can be delivered a little at a time into the holding pool and distributed to waiting signals mid-run; the result quantity may differ from the intent.
• Signals that leave their trip reconcile themselves. If an attached card signal leaves its trip — whether withdrawn or rolled over into its next lap — the demand item reconciles automatically: it detaches the signal, and cleans up if that leaves the demand item empty. Withdrawal is the half that works today; rollover closure is announced only in the design, so a rolled-over signal stays attached until something else detaches it (see Notifications).

How it relates to its neighbors

• Kanban Cards — the individual demand signals a demand item collates.
• Item — what a request produces.
• Inventory Item — the holding pool where produced materials accumulate.
• Processing Network — the station a request is produced at.
• Orders — an order line services one or more demand items, and as material is received the demand item records the production that fulfills it.