Items Module

Warning

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

Purpose¶

Items describe the types of materials, work in progress and finished goods that an organization
uses in its operations. Items contain information for inventory management, purchasing, sales and
production operations and transactions

Location in the System¶

Items Module will use other reference data modules such as Business Affiliates and Facilities as references for
some information of an item (e.g., who the supplier is, where the item is usually stocked, etc.)

Main Entities¶

For the long term information model of the Item Module see its Information Model

Version 1 (September 2025)¶

API¶

The API to the Item module is a Data Authority API that provides RESTful endpoints for managing item reference data with full bitemporal support.

The OpenApi Specification can be found in a Redocly Viewer

Locator Values for Query Filters and Sorting¶

In the future, a more robust locator system will be implemented, for now, the following values (case insensitive) can be
used in query filters for the Item Queries:

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
item_name	String	The name of the item
image_url	String (URL format)	The Url with the image of the item
classification_type	String	The Type of Item
classification_sub_type	String	The SubType of Item
use_case	String	The Use Case for the Item
physical_locator_facility	String	The Facility where the Item is stored
physical_locator_department	String	The Department where the Item is stored
physical_locator_location	String	The Location where the Item is stored
internal_sku	String	The SKU used by the company
notes	String	Free form text notes
card_notes_default	String	Default notes for Cards created for this item
taxable	BOOLEAN	Whether the product is taxable
primary_supply_supplier	String	The name of the primary supplier
primary_supply_sku	String	The Sku identification for the primary supplier
primary_supply_order_method	String	The preferred order method for the primary supplier
primary_supply_url	String (URL Format)	The Url of the product in the primary supplier systems
primary_supply_order_quantity_amount	Decimal Number	The amount of the item to be ordered from the primary supplier
primary_supply_order_quantity_unit	String	The Unit of measure of the order from the primary supplier
primary_supply_unit_cost_value	Decimal Number	The Unit Cost value in currency units
primary_supply_unit_cost_currency	String	The Currency in which the unit cost is expressed
primary_supply_average_lead_time_length	Integer	The number of time units that the item takes to arrive from the primary supplier
primary_supply_average_lead_time_time_unit	String	The units (SECOND, MINUTES, HOURS, DAYS, WEEKS) for the average time
secondary_supply_supplier	String
secondary_supply_sku	String
secondary_supply_order_method	String
secondary_supply_url	String (URL Format)
secondary_supply_order_quantity_amount	Decimal Number
secondary_supply_order_quantity_unit	String
secondary_supply_unit_cost_value	Decimal Number
secondary_supply_unit_cost_currency	String
secondary_supply_average_lead_time_length	Integer
secondary_supply_average_lead_time_time_unit	String
default_supply	String	The name of the primary or the secondary supplier
card_size	String	The type of card to be printed
label_size	String	The type of label to be printed
breadcrumb_size	String	The type of breadcrumb to be printed
item_color	String	The color to use in displaying the item

Service Layer¶

The Item module implements the service layer through the ItemService interface, providing business logic coordination between the API and persistence layers.

ItemService Interface¶

The service implements the standard EditableDataAuthorityService pattern:

interface ItemService : EditableDataAuthorityService<Item, ItemMetadata>

This provides:

Core Operations¶

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

Query Operations¶

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

Draft Operations¶

createDraft(payload: Item, metadata: ItemMetadata, author: String): DBIO<Draft<Item, ItemMetadata>>
readDraft(dId: UUID): DBIO<Draft<Item, ItemMetadata>?>
updateDraft(dId: UUID, payload: Item, metadata: ItemMetadata, author: String): DBIO<Draft<Item, ItemMetadata>>
deleteDraft(dId: UUID): DBIO<Unit>
publishDraft(dId: UUID, asOf: TimeCoordinates, author: String): DBIO<EntityRecord<Item, ItemMetadata>>

Service Implementation¶

The ItemService.Impl class coordinates:

Universe Operations: Delegates bitemporal entity operations to ItemUniverse
Draft Management: Uses DraftStore<Item, ItemMetadata> to manage drafts.
Transaction Management: Ensures ACID properties across operations
Validation: Orchestrates payload and business rule validation
Tenant Scoping: Ensures all operations respect tenant boundaries

Business Logic¶

The service layer implements business rules specific to item management:

Item Name Uniqueness: Within tenant scope
Classification Validation: Ensures valid category hierarchies
Supply Chain Constraints: Validates supplier codes and lead times
Physical Location Validation: Ensures warehouse and location codes exist
Quantity Validation: Validates units and amounts for supply requirements

Persistence Layer¶

The Item module implements a bitemporal persistence layer using the Arda Universe framework, providing full audit trails and time-travel capabilities.

`ItemUniverse`¶

The ItemUniverse class extends AbstractScopedUniverse to provide tenant-scoped item management:

class ItemUniverse : AbstractScopedUniverse<Item, ItemMetadata, ITEM_TABLE, ItemRecord>()

Key Components¶

Persistence: ItemRecord.Companion - Handles database mapping
Validator: ScopingValidator<Item, ItemMetadata> - Validates tenant scoping and business rules
Universal Condition: ItemUniversalCondition - Applies tenant filtering to all queries

Bitemporal Features¶

Effective Time: When item data is valid in the business domain
Recorded Time: When changes were recorded in the system.
Entity History: Complete audit trail of all item changes
Time Travel: Query item state at any point in time
Logical Deletion: Items are never physically deleted, only marked as retired

Database Schema¶

The persistence layer uses the following table structure:

CREATE TABLE item_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 item_bitemporal(r_id),
    author VARCHAR(255) NOT NULL,

    -- Scoping column
    tenant_id UUID NOT NULL,

    -- Item payload columns
    name VARCHAR(255) NOT NULL,
    description TEXT,

    -- Item classification (embedded)
    category VARCHAR(100) NOT NULL,
    subcategory VARCHAR(100),
    tags JSONB,

    -- Item supply (embedded)
    supplier VARCHAR(255) NOT NULL,
    supplier_code VARCHAR(100) NOT NULL,
    lead_time_days INTEGER NOT NULL,
    min_order_quantity_amount DECIMAL(19,4) NOT NULL,
    min_order_quantity_unit VARCHAR(50) NOT NULL,

    -- Physical locator (embedded)
    warehouse VARCHAR(100) NOT NULL,
    zone VARCHAR(50) NOT NULL,
    shelf VARCHAR(50) NOT NULL,
    bin VARCHAR(50) NOT NULL,

    -- Indexes for bitemporal queries
    UNIQUE(e_id, effective_as_of, recorded_as_of),
    INDEX idx_item_tenant_effective (tenant_id, effective_as_of),
    INDEX idx_item_tenant_recorded (tenant_id, recorded_as_of),
    INDEX idx_item_name (tenant_id, name),
    INDEX idx_item_category (tenant_id, category, subcategory)
);

`ItemRecord`¶

The ItemRecord class extends ScopedRecord to handle object-relational mapping:

class ItemRecord(rId: EntityID<UUID>) :
    ScopedRecord<Item, ItemMetadata, ITEM_TABLE, ItemRecord>(rId, ITEM_TABLE) {

    // Item payload properties
    var name by ITEM_TABLE.name
    var description by ITEM_TABLE.description

    // Classification properties
    var category by ITEM_TABLE.category
    var subcategory by ITEM_TABLE.subcategory
    var tags by ITEM_TABLE.tags

    // Supply properties
    var supplier by ITEM_TABLE.supplier
    var supplierCode by ITEM_TABLE.supplierCode
    var leadTimeDays by ITEM_TABLE.leadTimeDays
    var minOrderQuantityAmount by ITEM_TABLE.minOrderQuantityAmount
    var minOrderQuantityUnit by ITEM_TABLE.minOrderQuantityUnit

    // Physical locator properties
    var warehouse by ITEM_TABLE.warehouse
    var zone by ITEM_TABLE.zone
    var shelf by ITEM_TABLE.shelf
    var bin by ITEM_TABLE.bin

    override fun fillPayload(p: Item) {
        payload = p
        name = p.name
        description = p.description
        // Map other properties...
    }

    override fun fillMetadata(m: ItemMetadata) {
        metadata = m
        tenantId = m.tenantId
    }
}

Component Persistence¶

The module includes specialized component classes for complex domain objects:

`QuantityComponent`¶

Handles persistence of quantity values with amount and unit:

class QuantityComponent(table: Table, prefix: String = "") : Component<Quantity> {
    private val amountColumn = table.decimal("${prefix}amount", 19, 4)
    private val unitColumn = table.varchar("${prefix}unit", 50)

    override fun fillFrom(entity: Quantity) {
        // Map quantity to columns
    }

    override fun fillTo(): Quantity {
        // Map columns to quantity
    }
}

`ItemClassificationComponent`¶

Handles item categorization and tagging:

Maps category hierarchies to database columns
Serializes tags as JSONB for flexible querying
Supports category-based filtering and reporting

`ItemSupplyComponent`¶

Manages supply chain information:

Links to supplier systems
Tracks lead times and minimum order quantities
Supports supply chain analytics

`PhysicalLocatorComponent`¶

Handles warehouse location data:

Maps hierarchical location structure (warehouse → zone → shelf → bin)
Supports location-based inventory queries
Enables warehouse management integration

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
Full-Text Search: Search across item names and descriptions
Classification Filtering: Filter by categories, subcategories, and tags
Supply Chain Queries: Find items by supplier, lead time, or order requirements
Location-Based Queries: Find items by warehouse, zone, or specific locations
Aggregation Support: Count, sum, and group items by various dimensions