Mapping Kanban Card State to Procurement Workflow for MVP0/MVP1

Requirements¶

📄 Description¶

The goal of this spike is to clarify and document how each internal Kanban Card status should be represented and interpreted by the user — both in terminology and associated actions.
Currently, backend statuses like REQUESTING, REQUESTED, IN_PROCESS, and FULFILLED are not intuitive for end-users. This spike aims to define a human-readable mapping between the system statuses and the user-facing states and actions.

🎯 Objective¶

Establish a clear status → label → user action mapping that:

Simplifies user understanding of the card’s lifecycle.
Aligns with real-world user expectations (ordering → receiving → restocking).
Ensures consistent terminology across UI surfaces (Cards, Items, Order Queue, etc.).
Guides future UI/UX and logic implementations (button states, tooltips, etc.).

🧠 Proposed Mapping (Initial Hypothesis)¶

System Status (Backend)	User-Facing Label	Primary User Action	Description (User Context)
`REQUESTING`	🟠 In Order queue	Start order	Card has been added to the queue but not yet submitted. User can initiate the ordering process.
`REQUESTED`	🟡 In progress	Complete order	The order request has been made; awaiting confirmation or completion by supplier or user.
`IN_PROCESS`	🔵 Receive	Receive card	The item is currently being processed or shipped. The user can receive the card once the item arrives.
`FULFILLED`	🟢 Restocked	Restocked (no action)	The item has been received and restocked. Card cycle is complete and ready for next reorder trigger.

MVP0 and MVP1 Procurement Workflow¶

In the MVP0 and MVP 1 releases of the product, the Procurement Workflow for Kanban Cards is simplified:

There is a single Procurement Station for the entire shop.
Requests for Procurement are made from the rest of the shop without explicit identification of what station is making the request.
Users, in simple operations, may skip the explicit Receiving step.

The Lifecycle of a Kanban Card from the point of view of this simplified Procurement Workflow is:

If the user wants to skip the Receiving action, the workflow further simplifies to:

Transition Table for MVP0/MVP1 Procurement Workflow¶

The resulting transition table to support both workflows is:

The Mapping of User Facing States to Backend States is:

User-Facing State	Backend State
`New Card`	`AVAILABLE`
🟠 `In Order Queue`	`REQUESTING`
🟡 `In Progress`	`REQUESTED`
🔵 `Receiving`	`IN_PROCESS`
🟢 `Restocked`	`FULFILLED`

User State (BackEnd State)	User Action (Signal to backend)	Resulting State
`NONE`	Create Card (add card)	`New Card(AVAILABLE)`
`New Card(AVAILABLE)`	Save (`accept`)	`In Order Queue (REQUESTING)`
🟠 `In Order Queue (REQUESTING)`	Add to Order (`accept`)	🟡 `In Progress (REQUESTED)`
🟡 `In Progress (REQUESTED)`	Order (`start`)	🔵 `Receiving (IN_PROCESS)`
🟡 `In Progress (REQUESTED)`	Complete Order (`start`)	🟢 `Restocked (FULFILLED)`
🔵 `Receiving (IN_PROCESS)`	Receive (`receive`)	🟢 `Restocked (FULFILLED)`
🟢 `Restocked (FULFILLED)`	Add to Queue (`accept`)	🟠 `In Order Queue (REQUESTING)`

The Mapping of User Actions to backend Signals is:

User Action	Backend Signal
`Create Card`	`add card`
`Save`	`request`
`Add to Order`	`accept`
`Order`	`start`
`Complete Order`	`receive`
`Receive`	`receive`
`Add to Queue`	`request`

Review against complete Kanban Card Lifecycle¶

The Kanban Card lifecycle Defines 10 states for a Kanban Card from the point of view of its operations.

The Procurement Workflow is a pure Source Station from the point of view of the Kanban Network, which means that only 6 out of the 10 states are needed to fully describe its workflow. Their interpretation in the procurement context and the mapping to the user facing labels to be used in the UI is:

Kanban State	User-Facing Label	Procurement Workflow Interpretation
`AVAILABLE`	`New`	Initial state of the Card when it is created in the system. It shows up in the UI only when the card is being edited by the user for the first time before it is saved.
`REQUESTING`	🟠 `In Order queue`	The Card has been requested from a Station in the Shop, and it is waiting to be processed by the Procurement workshop.
`REQUESTED`	🟡 `In progress`	The Request for the Card has been accepted by the Procurement workshop, and it is being added to an Order to be sent to the supplier.
`IN_PROCESS`	🔵 `Ready to Receive`	The Card has been added to a Supplier Order and the order has been submitted to the supplier. Materials for the Card are expected to arrive from the supplier and will then be received by the procurement workflow
`READY`	N/A	Materials associated with the Card have arrived from the Supplier Received at the Procurement station. The Procurement station has not yet sent them to the requesting station.
`FULFILLING`	N/A	Materials associated with the Card have been received and sent to the requesting station.

In addition, the system tracks the FULFILLED state, which is the state the Card reaches once the requesting station has received the materials associated with the Card. The user sees this state as 🟢 Restocked

The actions available to the user at each state for the normal workflow (no exceptional flows) are:

State	User Action	Description	Signal to the Back End	Resulting State
`NONE`	Create Card	User Creates a new Card and the UI presents the form to fill in its details (with information taken from the Item)	None	`AVAILABLE`
`AVAILABLE`	Save	User Saves the Card with its details	`accept` (equivalent)	`REQUESTING`
`REQUESTING`	Start Order	User starts the order process for the Card	`accept`	`REQUESTED`
`REQUESTED`	Submit Order	User submits the order that services the Card	`start/order`	`IN_PROCESS`
`IN_PROCESS`	Receive	User receives the materials for the Card once they arrive from the Supplier	`complete`	`READY`
`READY`	Restock	The Procurement station sends the materials to the requesting station	`fulfill`	`FULFILLING`

After the FULFILLING state, the Kanban Card control is owned by the requesting station, which will move it to the FULFILLED state once the station takes delivery of the materials.

MVP0 and MVP1 Mapping¶

The simplifications for MVP0 and MVP1 result in:

The READY and FULFILLING states are not currently used, with the UI signalling the back end to move directly from IN_PROCESS or even REQUESTED to FULFILLED when the user either receives an order or completes it directly from the procurement workflow.