Demand Module

Status: In development — implementation under review (operations PR #219). The design described here is being built; it is the collation layer between the kanban replenishment loop and orders.

Purpose

A production request — the Demand module’s central concept — is an intent to produce a quantity of an item at a particular station. 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 production request gathers many card signals (and direct, card-less demand) into one production task. Downstream, Orders service production requests; 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 production request — or wait on their own — is a business choice made by whoever composes the request. The module owns only the integrity half: eligibility, no double-holding, and the lifecycle rules.

Main entities

• Production request (the DemandItem) — 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.
• It references card signals from the Kanban Cards module and a holding pool from the Inventory Item module.

Lifecycle

A production request 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.

Operations

Action	What it does	When it is allowed
Create	Starts a request — empty, or from its first card signal.	Any time.
Add / remove signal	Collates a card signal into the request, or returns it to the queue.	While Open.
Adjust quantity	Sets the intended total.	While Open.
Release	Hands the request 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.
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 request 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 production request 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 request 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 request reconciles automatically: it detaches the signal, and cleans up if that leaves the request empty.

How it relates to its neighbors

• Kanban Cards — the individual demand signals a production request 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 production requests, and as material is received the request records the production that fulfills it.