Kanban Cards Module

Purpose

Kanban Cards manage physical and digital kanban cards used in lean manufacturing and inventory management. Cards signal the need to replenish inventory, initiate production, or trigger material movement between process steps.

Integrations

• Items Module: References the item a card represents
• Serial Number Service: Generates unique identifiers for physical cards
• Facilities Module: Tracks card location within warehouses and production areas

Main Entities

API

OpenAPI specification: https://stage.alpha002.io.arda.cards/v1/kanban/docs/redoc/index.html#tag/v1

Query Locator Fields

Universes configured with EntityServiceConfiguration accept both JSON field paths (camelCase) and database column names (snake_case) as locators. The table below shows both forms. See Query DSL: EntityServiceConfiguration.

JSON Field Path	Column Name	Type	Description
eId	eid	uuid	Entity UUID
serialNumber	kanban_card_sn	String	Card serial number
itemReference.entityId	item_reference_entity_id	uuid	Associated item entity ID
itemReference.itemName	item_reference_item_name	String	Associated item name
cardQuantity.amount	card_quantity_amount	Decimal	Inventory quantity represented
cardQuantity.unit	card_quantity_unit	String	Inventory unit of measure
requestLocation.facility	physical_locator_facility	String	Current facility
requestLocation.department	physical_locator_department	String	Current department
requestLocation.location	physical_locator_location	String	Current location
status	status	String	Current card status
printStatus	print_status	String	Current print status
—	id	uuid	Record ID (bitemporal)
—	effective_as_of	TIMESTAMP	Bitemporal effective timestamp
—	recorded_as_of	TIMESTAMP	Bitemporal recorded timestamp
—	retired	BOOLEAN	Whether logically deleted
—	tenant_id	uuid	Owning tenant
—	last_event_*	various	Fields describing the most recent lifecycle event
—	last_print_event_*	various	Fields describing the most recent print event

Service Layer

KanbanCardService implements DataAuthorityService<KanbanCard, KanbanCardMetadata>.

Core Operations

• create, read, update, delete
• list, count, history
• summaryByStatus — aggregates cards by status with quantity totals
• listWithDetails — returns cards with full item details

Lifecycle Management

Two specialized lifecycle interfaces:

KanbanCardLifecycle — operational state transitions:

REQUESTED -> ACCEPTED -> IN_PROCESS -> COMPLETED -> FULFILLED -> RECEIVED -> IN_USE -> DEPLETED -> WITHDRAWN

Methods: request, accept, startProcessing, completeProcessing, fulfill, receive, use, deplete, withdraw

KanbanCardPrintLifecycle — print state management:

NOT_PRINTED -> PRINTED (print)
PRINTED -> PRINTED (reprint)
PRINTED -> NOT_PRINTED (unmark)
PRINTED -> LOST (reportLost)
PRINTED -> DEPRECATED (deprecate)
PRINTED -> RETIRED (retire)
DEPRECATED -> LOST (reportLost)
DEPRECATED -> RETIRED (retire)
LOST -> PRINTED (reprint)
LOST -> RETIRED (retire)

Methods: printCards, cardPrinted, reprint, reportLost, retire, unmarkPrinted

The unmarkPrinted method transitions a card from PRINTED to NOT_PRINTED. It is a no-op for cards not in PRINTED status (idempotent for NOT_PRINTED). Exposed via POST /kanban-card/{eId}/event/unmark.

Business Rules

• Serial number uniqueness within tenant scope
• Valid lifecycle state transitions
• Item reference validation
• Location tracking on lifecycle transitions
• Print status management

Notes

Kanban cards support a free-text notes field (up to 8192 characters, nullable). Notes are initialized from the item’s defaults when a card is created and can be updated independently via a dedicated endpoint. See Kanban Card Notes for the feature specification.

Persistence Layer

KanbanCardUniverse extends AbstractScopedUniverse<KanbanCard, KanbanCardMetadata, KANBAN_CARD_TABLE, KanbanCardRecord>().

Event sourcing tables:

• kanban_card_event — lifecycle state changes
• kanban_card_print_event — print lifecycle changes

Both tables record event_type, from_status, to_status, location, timestamps, and author.

QR Code Lookup URL

Physical cards include a QR code linking to:

https://{base-url}/kanban/cards/{kanban-card-id}?view=card&src=qr

Base URLs by Environment

Environment	Base URL
Production	live.app.arda.cards
Staging	stage.app.arda.cards
Development	dev.app.arda.cards

QR Code Physical Specification

Property	Value
Encoding	URL string encoded as QR code
Error correction	Level M (15% recovery) — suitable for shop floor conditions where cards may be scratched or dirty
Minimum print size	20 mm x 20 mm at 300 DPI for reliable scanning with mobile phone cameras
Label placement	Bottom-right quadrant of the card, with at least 4 mm quiet zone on all sides
Human-readable fallback	Card serial number printed below the QR code in OCR-B font for manual lookup when scanning fails

Resolving a Card ID from the API

The card eId is available via the query endpoint:

POST /v1/kanban/kanban-card/query

Authentication: Bearer token. Pass the tenant identifier in the X-Tenant-Id request header.

Pagination: Default page size is 20; maximum is 500. Use the pageSize query parameter to increase the limit within that bound.

Extracting the ID: The entity identifier is at results[*].payload.eId in the response body.

API documentation:

• OpenAPI: https://prod.alpha001.io.arda.cards/v1/kanban/docs/openApi.json
• Swagger UI: https://prod.alpha001.io.arda.cards/v1/kanban/docs/openapi/index.html
• Redoc: https://prod.alpha001.io.arda.cards/v1/kanban/docs/redoc/index.html