Kanban Cards Module

Status: Live (lifecycle redesign in progress). The module ships today; the operational lifecycle described here is being tightened from the looser behavior in the live system. The full engineering reference for what ships today is kept at Kanban Cards (Q2 2026).

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

Purpose

A kanban card is the pull-replenishment signal for an item: a standing authorization to replenish a specific item in a specific quantity. When stock is drawn down, the card signals the need and travels back toward the point that supplies it; when materials are produced or procured, the card carries them forward to the point of use. It is the shop-floor unit of demand.

The module has two parts:

• The durable card — its identity, its configuration (which item, what quantity), and its printed artifact (with a QR code).
• The cycle — one lap of the replenishment loop: the live operational state of a single round trip. A card runs one cycle at a time and rolls over to a new cycle each time demand is re-triggered.

Context

Kanban Cards is the pull-signal layer of the domain map: one module builds on it, and it builds on three. 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.

Note

Loops are designed, not implemented — as of 2026-09-15. This diagram shows Kanban Cards depending on the Processing Network for the loop a card travels. That dependency is designed and does not exist in the runtime: there is no loop type, and no card carries a loop reference. The edge is kept because it is the designed shape; the date is here so a reader can tell how current that statement is.

What this module consumes:

• Item — each card represents an item through a floating reference: the card shows the item as it is today, every time it resolves it.
• Inventory Items — when a card starts processing, the cycle mints a pool of the card’s item and attaches it in the same act; a production failure clears it. Built and not yet in the running system, as of 2026-10-06 (operations#316, release R03): today no card references a pool — see the data model.
• Processing Network — the loop a card travels: which station consumes and which supplies. Designed, not built — the runtime has no loop type, so no card carries a loop reference today.

What its clients consume from it:

• Demand — demand items collate card signals; demand reads the cycle’s state at its own commit gates, while the loop stays unaware of demand — a card just emits its signal.

Functional decomposition

The module has two services, matching its two entities. They depend one way — cycles on cards, never the reverse — and each provides its own endpoint.

• KanbanCard service — owns the durable card: its identity, its configuration (which item, what quantity, and — in the design only, since the runtime has no loop type — which loop), and the print-state operations (print, reprint, report lost, retire), through the Cards API. The card knows nothing of the lap machinery — its “current cycle” is a derived reading.
• CardCycle service — owns the replenishment lap: the cycle operations (request, accept, shelve, start, ready, fulfill, receive, use, deplete, roll over, withdraw), through the Cycles API. It depends on the KanbanCard service — a cycle is a lap of exactly one card and reads that card’s configuration — while the two lifecycles move independently by design: printing a replacement label mid-lap does not touch the cycle. Retiring a card does require its live lap to end first — by withdrawal or by rollover — because a card is deletable only while it has no live cycle (see Lifecycle).

Main entities

• Kanban card — the durable signal: which item it replenishes, the target quantity, and its print state. It exists independently of whether it is currently circulating.
• Card cycle — one lap of the loop, carrying the operational state and the materials in flight during that lap.

Lifecycle

The cycle — one lap

A card cycle runs a loop: demand travels from the point of use back to the point that supplies it, materials are produced or procured, and they travel forward to be consumed — after which demand is re-triggered and the next lap begins. Available is not a lap state: it is the card-level reading “this card has no live cycle.” A card rests at Available before its first lap, and returns there one way only — withdraw, which ends the live lap (rather than moving it to another state) and is allowed at any point in it. The normal end of a lap never passes through Available: re-triggering demand closes the current cycle and opens the next in one act (rollover).

On retiring a card, and where that rule’s authority comes from. The diagram shows retirement from AVAILABLE only, and that is exact: a card is deletable just while it has no live cycle, so a card mid-lap must be withdrawn or rolled over first. The runtime refuses a mid-cycle delete and a test pins the refusal. The model does not yet carry a card log, so today the rule rests on the runtime’s tested behaviour plus a queued model delta rather than on a model law — read it as a statement about the system as built.

The lifecycle redesign underway replaces the live system’s loose behavior — which today lets a card move from almost any state to almost any other — with an explicit rule: a card advances forward along the lap (and may skip stages a given site does not perform, such as a site with no formal receiving step), plus a few named exceptions — starting the next lap with a new demand signal (which closes out the current lap; allowed once the card’s materials are ready, from materials ready through fully depleted), pulling a card back out of an order that was never submitted (shelve), reporting that a replenishment attempt produced nothing for this card (which returns it to the request queue), and withdrawing a card from circulation (possible at any point in the lap). Backward or arbitrary jumps are no longer allowed.

The card itself

The card’s own life is separate from any single trip: whether it has been printed, reprinted, reported lost, or retired. A card can sit at any point in its replenishment lap while its print state changes underneath it — printing a replacement label mid-trip does not touch the cycle. Retiring is the exception that does depend on the trip: a card is deletable only while it has no live cycle, so a card mid-lap must be withdrawn or rolled over first — the runtime refuses a mid-cycle delete, and a test pins the refusal.

Notifications

Every action recorded against a card cycle is observable to the rest of the system — see how modules stay in sync.

What this module announces

• When a card is withdrawn, the module announces it and Demand detaches that card’s signal from whatever demand item it was collated into. That is what ships today. Extending the same announcement to the other way a trip ends — the next lap beginning through the ordinary rollover — is designed and not yet built, so a rollover closure produces no announcement in the runtime at present.

What this module listens for

• Item new, update and delete — a new item gets a default card, an update refreshes the cards linked to it, and a delete stamps their item reference as retired (see the data model). Beyond that upkeep, Kanban Cards reacts to no operational-workflow notification: the kanban loop is the most upstream signal source in the system.

Scenarios

Three moments show the card’s 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.

A card runs the full lap, from being put into circulation to being used up, and its depletion re-triggers demand for the next lap on the same card.

A card can also leave circulation early. Withdrawing it ends its trip immediately, and the module’s announcement lets Demand let go of the signal on its own.

Some sites don’t run every stage of the loop — a site with no formal receiving step can skip straight from “requested” to “in process,” for example. But skipping a stage the site does use is refused, not silently allowed.

These scenarios are verified against the formal model.

Operations

Action	What it does	Notes
Request	Puts a card into circulation, or re-triggers demand for a new lap.	Starts a cycle.
Accept	Takes the demand into the order queue.
Shelve	Pulls a card back out of an order that was never submitted.	The corrective exception.
Start / complete replenishment	Advances the card through procurement or production.
Report production failure	Reports that a replenishment attempt produced nothing for this card; returns it to the request queue.	The other corrective exception; releases any attached materials.
Fulfill / receive	Moves materials to the point of use and records their arrival.
Use / deplete	Records consumption until the card is empty.	Ends the lap.
Withdraw	Removes a card from circulation.
Print / reprint / report lost	Manage the card’s printed artifact.	Independent of the operational state.
Retire	Ends the card’s own life.	Requires no live cycle — withdraw or roll over first; a mid-cycle delete is refused.

Guarantees

• One cycle at a time. A card runs a single live cycle; a new lap begins only when demand is re-triggered.
• A lap ends one of two ways, and the two are distinct. A lap either rolls over into the next one (recorded as completed) or is withdrawn (recorded as abandoned); once ended, it is final. A card withdrawn and later re-requested reads as abandoned, not completed.
• Moves are disciplined. Under the redesign, a card advances forward along its lap (skips allowed) plus the few named exceptions — not the anything-goes transitions of the live system.
• Print state is independent — retiring is not. Whether a card is printed, reprinted or reported lost is tracked separately from where it is in its replenishment lap. Retiring the card is the one exception: it requires no live cycle, so a card mid-lap must be withdrawn or rolled over first.
• A deleted item does not break a card. A card keeps resolving even after the item it references is deleted, showing the item’s last-known name with a deleted marker.

How it relates to its neighbors

• Item — every card replenishes one item.
• Inventory Item — the materials a loaded card carries are inventory holdings.
• Demand — cards are the individual demand signals that the Demand module collates into demand items.
• Processing Network — cards circulate within the loops that connect stations.