Flow → API Walkthroughs

A walkthrough takes one flow from the Business Flows and re-tells its business steps as concrete API calls: the exact METHOD /path, the request fields that matter, what state changes on the far side, the refusals a caller can hit, and a pointer to the api-test that proves it. Where the narrative and the running system disagree, the walkthrough says so plainly, in a Fidelity notes section on each page — that is review material, not a defect list.

Walkthroughs are for engineers who already know the product domain and want to go from “what does the flow say happens” to “what do I actually call, and what can go wrong.” They assume the module pages as the specification; a walkthrough is a value-ordered tour through calls, not a restatement of state machines.

The shared call shape

Before reading a walkthrough, it helps to know the one convention nearly every call in these pages follows — stating it once here means the per-flow pages don’t have to repeat it on every row.

The orders-v2 call shape

Mutations are POST /v1/<domain>/<module>/<subject>/<verb>, with the target record’s id in the request body (never a query parameter), plus an effectiveAsOf timestamp (epoch milliseconds). create and add-line calls mint their own id instead of taking one.

Reads are GET .../{eId}, with an optional asOf timestamp to read a past version.

Refusals come back as an HTTP status driven by the failure’s category: 409 for a PRECONDITION failure (a state the caller could have checked first), 403 for a POLICY failure (a rule the caller isn’t allowed to override). Either way, the response carries a stable, documented reason code on the wire — RFrozen, RDemandHeld, RRetiredRef, and so on — so a caller can branch on why, not just that, a call was refused.

Kanban is the one exception. It predates this convention: card events are POST .../{eId}/event/{event} with twin effectiveasof / recordedasof query parameters and no body. An event response returns {event, previous} — the card’s status before the event, not after — which is why every kanban walkthrough step re-reads the card to see the status the event produced.

Built vs. designed

Every step table marks its API-call cell one of four ways:

Marking	Meaning
POST /v1/... (a real call, in code font)	Built — a live, callable, and (usually) tested endpoint.
designed — Receiving (italic)	Designed, not built. The Receiving module is fully specified on its module page but has no Kotlin package, route, or test yet — every dock-side capture and freeze step falls here today.
— (physical step)	A human or physical action with no API surface at all — goods arriving on a truck, a clerk restocking a shelf. There is nothing to call because nothing in the step is a system interaction.
— (see Fidelity notes)	A step with neither a built call nor a Receiving-shaped design behind it — usually because the narrative’s own claim about system behavior (a notification, a coupling) doesn’t hold up against the running code. The page’s Fidelity notes section explains each of these individually.

The four walkthroughs land very differently on this spectrum: frozen-commitments is 26 of 27 steps built and tested; dock-reality has not one callable step, because every step in it is a Receiving-module behavior.

The walkthroughs

• Walkthrough: The Pull-Replenishment Round Trip — the flagship flow’s four legs, from a card’s scan through demand collation, order commitment, dock receipt, and distribution back to the shelf. Leg 2 (order composition) is solid; Leg 3 (receipt) is the flow’s biggest gap.
• Walkthrough: Commitments That Cannot Be Silently Edited — the best-covered of the four: draft composition, the four-check submission floor, the freeze, and deliberate closure, almost entirely built and tested.
• Walkthrough: Receiving You Can Trust — split cleanly down the middle: the dock-side capture and freeze are entirely unbuilt, while the order’s self-reconciling received amounts are fully implemented.
• Walkthrough: Reality at the Dock — every step is a Receiving-module behavior, so every step is designed rather than built; this page shows what the API surface will owe the flow once Receiving ships, using the nearest built analogues where they exist.

Read next

• Business Flows — the narrative pages these walkthroughs trace.
• Functional domains overview — the module pages that are the actual specification.