Kanban Cards Module

Warning

This is partially Generated with AI Copilot. Although reviewed by a human, it may still contain errors or inaccuracies.

Purpose¶

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

Location in the System¶

The Kanban Cards module integrates with:

Items Module: References items that kanban cards represent
Serial Number Service: Generates unique identifiers for physical cards
Facilities Module: Tracks card locations within warehouses and production areas

Main Entities¶

API¶

The API to the Kanban Cards module provides RESTful endpoints for managing kanban cards with full lifecycle support and bitemporal tracking.

The OpenApi Specification can be found in a Redocly Viewer

Locator Values for Query Filters and Sorting¶

Locator Value	Data Type	Description
id	uuid	The Record Id (bitemporal)
effective_as_of	TIMESTAMP	The Bitemporal Effective Timestamp
recorded_as_of	TIMESTAMP	The Bitemporal Recorded Timestamp
author	String	The User Id that performed the last change
eid	uuid	The UUID for the Entity
previous	uuid	The Record Id of the preceding version
retired	BOOLEAN	Whether the entity has been deleted
tenant_id	uuid	The Id of the owning tenant
kanban_card_sn	String	The serial number of the Card
item_reference_entity_id	uuid	The Entity Id of the Associated Item
item_reference_item_name	String	The Name of the Associated Item
item_reference_record_id	uuid	The recordId (if present) of the Associated Item version
card_quantity_amount	Decimal Number	The amount of inventory the card represents
card_quantity_unit	String	The Units in which the inventory is measured
physical_locator_facility	String	The Facility where the card is currently located
physical_locator_department	String	The Department where the card is currently located
physical_locator_location	String	The Location where the card is currently located
last_event_at_time_effective	Integer	The Effective Time of the last event affecting the card
last_event_at_time_recorded	Integer	The Recorded Time of the last event affecting the card
last_event_kanban_card_event_type	String	The Event Type of the last event (See lifecycle)
last_event_from_where_facility	String	The facility where the card was before the last event
last_event_from_where_department	String	The Department where the card was before the last event
last_event_from_where_location	String	The Location where the card was before the last event
last_event_to_where_facility	String	The Facility where the card is after the last event
last_event_to_where_department	String	The Department where the card is after the last event
last_event_to_where_location	String	The Location where the card is after the last event
last_event_author	String	The user Id that caused the last event
status	String	The current status of the Item (see lifecycle)
last_print_event_at_time_effective	BIGINT	The Effective time of the last print event.
last_print_event_at_time_recorded	BIGINT	The Recorded time of the last print event.
last_print_event_kanban_card_event_type	String	The Last Print Event Type (see lifecycle)
last_print_event_author	String	The user that cause the last print event
print_status	String	The current print status

Service Layer¶

The Kanban Cards module implements a sophisticated service layer with lifecycle management, print tracking, and integration with external services.

KanbanCardService Interface¶

The service extends the standard DataAuthorityService pattern with kanban-specific functionality:

interface KanbanCardService : DataAuthorityService<KanbanCard, KanbanCardMetadata>

Core Data Authority Operations¶

create(payload: KanbanCard, metadata: KanbanCardMetadata, asOf: TimeCoordinates, author: String): DBIO<EntityRecord<KanbanCard, KanbanCardMetadata>>
read(eId: UUID, asOf: TimeCoordinates, includeRetired: Boolean): DBIO<EntityRecord<KanbanCard, KanbanCardMetadata>?>
update(update: EntityUpdate<KanbanCard, KanbanCardMetadata>): DBIO<EntityRecord<KanbanCard, KanbanCardMetadata>>
delete(eId: UUID, metadata: KanbanCardMetadata, asOf: TimeCoordinates, author: String): DBIO<EntityRecord<KanbanCard, KanbanCardMetadata>>

Query Operations¶

list(query: Query, asOf: TimeCoordinates, includeRetired: Boolean, withTotal: Boolean): DBIO<Page<KanbanCard, KanbanCardMetadata>>
count(filter: Filter, asOf: TimeCoordinates, includeRetired: Boolean): DBIO<Long>
history(eId: UUID, from: TimeCoordinates, to: TimeCoordinates, page: Pagination): DBIO<Page<KanbanCard, KanbanCardMetadata>>

Summary Operations¶

summaryByStatus(condition: Filter, asOf: TimeCoordinates, includeRetired: Boolean, vararg forStatus: KanbanCardStatus): DBIO<List<KanbanCardSummary>>

Query Details Operations¶

listWithDetails(query: Query, asOf: TimeCoordinates = TimeCoordinates.now()): Result<PageResult<KanbanCardDetails, KanbanCardMetadata>>

Lifecycle Management¶

The service implements two specialized lifecycle interfaces:

KanbanCardLifecycle¶

Manages the operational states of kanban cards:

interface KanbanCardLifecycle : LogEnabled {
    suspend fun request(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun accept(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun startProcessing(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun completeProcessing(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun fulfill(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun receive(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun use(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun deplete(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
    suspend fun withdraw(card: KanbanCardReference, location: PhysicalLocator.Value?, effectiveTime: Timestamp, author: String): Result<KanbanCardStateChange>
}

KanbanCardPrintLifecycle¶

Manages the physical printing and tracking of kanban cards:

interface KanbanCardPrintLifecycle : LogEnabled {
    suspend fun print(card: KanbanCardReference, effectiveTime: Timestamp, author: String): Result<KanbanCardPrintStateChange>
    suspend fun reprint(card: KanbanCardReference, effectiveTime: Timestamp, author: String): Result<KanbanCardPrintStateChange>
    suspend fun reportLost(card: KanbanCardReference, effectiveTime: Timestamp, author: String): Result<KanbanCardPrintStateChange>
    suspend fun retire(card: KanbanCardReference, effectiveTime: Timestamp, author: String): Result<KanbanCardPrintStateChange>
}

Service Implementation¶

The ServiceImpl class coordinates:

Universe Operations: Delegates bitemporal entity operations to KanbanCardUniverse
Item Service Integration: Validates item references and retrieves item data
Serial Number Generation: Uses SerialNumberService for unique card identifiers
State Validation: Ensures valid lifecycle state transitions
Event Tracking: Records lifecycle events with timestamps and locations
Transaction Management: Ensures ACID properties across operations
Tenant Scoping: Ensures all operations respect tenant boundaries

Business Logic¶

The service layer implements business rules specific to kanban card management:

Serial Number Uniqueness: Within tenant scope
State Transition Validation: Ensures valid lifecycle progressions
Item Reference Validation: Verifies items exist and are accessible
Location Tracking: Records location changes during lifecycle transitions
Print Status Management: Tracks physical card printing and replacement
Quantity Consistency: Validates quantities match item definitions

Persistence Layer¶

The Kanban Cards module implements a bitemporal persistence layer using the Arda Universe framework with event sourcing for lifecycle tracking.

KanbanCardUniverse¶

The KanbanCardUniverse class extends AbstractScopedUniverse to provide tenant-scoped kanban card management:

class KanbanCardUniverse : AbstractScopedUniverse<KanbanCard, KanbanCardMetadata, KANBAN_CARD_TABLE, KanbanCardRecord>()

Key Components¶

Persistence: KanbanCardRecord.Companion - Handles database mapping
Validator: ScopingValidator<KanbanCard, KanbanCardMetadata> - Validates tenant scoping and business rules
Universal Condition: KanbanCardUniversalCondition - Applies tenant filtering to all queries

Custom Aggregation Methods¶

The universe provides specialized query methods:

suspend fun summaryByStatus(
    condition: Filter,
    asOf: TimeCoordinates,
    includeRetired: Boolean,
    vararg forStatus: KanbanCardStatus
): DBIO<List<KanbanCardSummary>>

This method aggregates kanban cards by status with quantity totals, supporting lean manufacturing reporting and dashboard views.

Database Schema¶

The persistence layer uses the following table structure:

CREATE TABLE kanban_card_bitemporal (
    -- Bitemporal columns
    r_id UUID PRIMARY KEY,
    e_id UUID NOT NULL,
    effective_as_of TIMESTAMPTZ NOT NULL,
    recorded_as_of TIMESTAMPTZ NOT NULL,
    retired BOOLEAN NOT NULL DEFAULT FALSE,
    previous UUID NULL REFERENCES kanban_card_bitemporal(r_id),
    author VARCHAR(255) NOT NULL,

    -- Scoping column
    tenant_id UUID NOT NULL,

    -- Kanban card payload columns
    serial_number VARCHAR(50) NOT NULL,
    status VARCHAR(20) NOT NULL,
    print_status VARCHAR(20) NOT NULL,

    -- Item reference (embedded)
    item_eid UUID NOT NULL,
    item_name VARCHAR(255) NOT NULL,

    -- Card quantity (embedded)
    card_quantity_amount DECIMAL(19,4) NOT NULL,
    card_quantity_unit VARCHAR(50) NOT NULL,

    -- Request location (embedded)
    request_warehouse VARCHAR(100) NOT NULL,
    request_zone VARCHAR(50) NOT NULL,
    request_shelf VARCHAR(50) NOT NULL,
    request_bin VARCHAR(50) NOT NULL,

    -- Fulfill location (embedded)
    fulfill_warehouse VARCHAR(100) NOT NULL,
    fulfill_zone VARCHAR(50) NOT NULL,
    fulfill_shelf VARCHAR(50) NOT NULL,
    fulfill_bin VARCHAR(50) NOT NULL,

    -- Indexes for bitemporal queries
    UNIQUE(e_id, effective_as_of, recorded_as_of),
    UNIQUE(tenant_id, serial_number, effective_as_of),
    INDEX idx_kanban_tenant_effective (tenant_id, effective_as_of),
    INDEX idx_kanban_tenant_recorded (tenant_id, recorded_as_of),
    INDEX idx_kanban_status (tenant_id, status),
    INDEX idx_kanban_item (tenant_id, item_eid),
    INDEX idx_kanban_serial (tenant_id, serial_number)
);

Event Tables¶

The module includes specialized event tables for lifecycle tracking:

CREATE TABLE kanban_card_event (
    event_id UUID PRIMARY KEY,
    card_eid UUID NOT NULL,
    tenant_id UUID NOT NULL,
    event_type VARCHAR(50) NOT NULL,
    from_status VARCHAR(20),
    to_status VARCHAR(20),
    location_warehouse VARCHAR(100),
    location_zone VARCHAR(50),
    location_shelf VARCHAR(50),
    location_bin VARCHAR(50),
    effective_time TIMESTAMPTZ NOT NULL,
    recorded_time TIMESTAMPTZ NOT NULL,
    author VARCHAR(255) NOT NULL,

    INDEX idx_event_card (tenant_id, card_eid, effective_time),
    INDEX idx_event_type (tenant_id, event_type, effective_time),
    INDEX idx_event_status (tenant_id, to_status, effective_time)
);

CREATE TABLE kanban_card_print_event (
    event_id UUID PRIMARY KEY,
    card_eid UUID NOT NULL,
    tenant_id UUID NOT NULL,
    event_type VARCHAR(50) NOT NULL,
    from_print_status VARCHAR(20),
    to_print_status VARCHAR(20),
    effective_time TIMESTAMPTZ NOT NULL,
    recorded_time TIMESTAMPTZ NOT NULL,
    author VARCHAR(255) NOT NULL,

    INDEX idx_print_event_card (tenant_id, card_eid, effective_time),
    INDEX idx_print_event_type (tenant_id, event_type, effective_time)
);

Component Persistence¶

The module includes specialized component classes for complex domain objects:

KanbanCardEventComponent¶

Handles persistence of lifecycle events:

class KanbanCardEventComponent : Component<KanbanCardEvent> {
    // Maps lifecycle events to database columns
    // Supports querying event history by card, type, and time range
}

KanbanCardPrintEventComponent¶

Manages print lifecycle events:

class KanbanCardPrintEventComponent : Component<KanbanCardPrintEvent> {
    // Maps print events to database columns
    // Tracks physical card printing, reprinting, and retirement
}

Query Capabilities¶

The persistence layer supports rich querying through the Universe framework:

Tenant-Scoped Queries: All queries automatically filtered by tenant
Bitemporal Queries: Query data as it existed at any point in time
Status-Based Filtering: Find cards by current or historical status
Item-Based Queries: Find cards by referenced items
Location-Based Queries: Find cards by request or fulfill locations
Serial Number Lookup: Unique identification within tenant scope
Event History: Complete audit trail of all lifecycle transitions
Aggregation Support: Count, sum quantities, and group by status or location
Print Status Tracking: Query cards by print status and print events

Integration Features¶

Item Service Integration: Automatic validation of item references
Serial Number Generation: Integration with SerialNumberService for unique identifiers
Location Validation: Ensures warehouse and location codes exist
Event Sourcing: Complete audit trail of all state changes with timestamps and authors