Item Module

Items describe the types of materials, work-in-progress, and finished goods that an organization uses in its operations. The module supports inventory management, purchasing, sales, and production.

Purpose

The Item module provides a Data Authority API for managing item reference data with full bitemporal support. Beyond the standard CRUDQ operations, it adds supply management, lookup services for typeahead fields, image upload, and printing of labels and breadcrumbs.

Integrations

• Business Affiliates Module (reference.businessAffiliate): Resolves supplier references in item supply records
• PDF Render Module (shopAccess.pdfRender): Renders label and breadcrumb PDFs via Documint. See PDF Render Module
• S3 Asset Service (common-module): Manages CSV upload and image upload storage
• Kanban Cards Module (resources.kanban): Observes item changes via DataAuthorityNotification to keep card data in sync

Block Diagram

Entity Model

API Endpoints

The module base path is /v1/item. All routes except lookups require authentication.

Data Authority (CRUDQ)

Inherited from EditableDataAuthorityEndpoint:

Method	Path	Description
POST	/item/add	Create item (or draft)
PUT	/item/update	Update item
GET	/item/{id}	Read item by record ID
DELETE	/item/{id}	Logical delete (retire)
POST	/item/query	Query with filters, sort, pagination
GET	/item/query/{pageToken}	Navigate paginated results
GET	/item/{id}/history	Entity version history

Query parameter mutation-mode (default: PROPAGATE) controls supply reference behavior: STRICT (verify existing), LAX (allow unlinked), PROPAGATE (create/update supplies with item).

Supply Management

Method	Path	Description
POST	/item/{parent-item-id}/supply/	Create item supply
PUT	/item/{parent-item-id}/supply/{supply-id}	Update item supply
DELETE	/item/{parent-item-id}/supply/{supply-id}	Remove item supply
GET	/item/{parent-item-id}/supply/	List item supplies

Printing

Method	Path	Request	Response	Description
POST	/item/item-print-label	EntityIdsInput (list of item UUIDs)	CompositeRenderResult	Print labels for items
POST	/item/item-print-breadcrumb	EntityIdsInput (list of item UUIDs)	CompositeRenderResult	Print breadcrumbs for items

Both accept optional query parameters:

Parameter	Type	Default	Description
live-print	Boolean	false	Production rendering (true) vs test/preview with watermark (false)
debug	Boolean	false	Include the Documint payload in the response (debugPayload field)
dry-run	Boolean	false	Construct payload but skip Documint call. No side effects. Overrides live-print and debug.

Image Upload

Method	Path	Request	Response	Description
POST	/item/{eId}/image-upload-url	ImageUploadRequest	ImageUploadResponse	Generate presigned upload credentials

Lookups (Unauthenticated)

All lookups accept name (search term) and limit (max results) query parameters and return List<String> (or List<ItemLookupResult> for items).

Method	Path	Description
GET	/item/lookup-suppliers	Supplier names
GET	/item/lookup-units	Quantity units
GET	/item/lookup-items	Item names + EIDs
GET	/item/lookup-types	Classification types
GET	/item/lookup-subtypes	Classification subtypes
GET	/item/lookup-usecases	Use cases
GET	/item/lookup-facilities	Facilities
GET	/item/lookup-departments	Departments
GET	/item/lookup-locations	Locations
GET	/item/lookup-sublocations	Sublocations

The OpenAPI specification is available via Redocly at https://stage.alpha002.io.arda.cards/v1/item/docs/redoc/index.html#tag/v1.

Query Locator Fields

The following fields (case-insensitive) are accepted in query filters and sort parameters:

Locator	Type	Description
id	uuid	Record ID (bitemporal)
effective_as_of	TIMESTAMP	Bitemporal effective timestamp
recorded_as_of	TIMESTAMP	Bitemporal recorded timestamp
eid	uuid	Entity UUID
retired	BOOLEAN	Whether logically deleted
tenant_id	uuid	Owning tenant
item_name	String	Item name
image_url	String (URL)	Product image URL
classification_type	String	Item type
classification_sub_type	String	Item sub-type
use_case	String	Use case label
physical_locator_facility	String	Storage facility
physical_locator_department	String	Storage department
physical_locator_location	String	Storage location
internal_sku	String	Internal SKU
notes	String	Free-form notes
card_notes_default	String	Default card notes
taxable	BOOLEAN	Taxable flag
primary_supply_supplier	String	Primary supplier name
primary_supply_sku	String	Primary supplier SKU
primary_supply_order_method	String	Preferred order method
primary_supply_url	String (URL)	Supplier product URL
primary_supply_order_quantity_amount	Decimal	Order quantity amount
primary_supply_order_quantity_unit	String	Order quantity unit
primary_supply_unit_cost_value	Decimal	Unit cost
primary_supply_unit_cost_currency	String	Currency
primary_supply_average_lead_time_length	Integer	Lead time length
primary_supply_average_lead_time_time_unit	String	Time unit
secondary_supply_*	(same as primary)	Secondary supplier fields
default_supply	String	Default supplier name
default_supply_eid	uuid	Default supply UUID
card_size	String	Card print size
label_size	String	Label print size
breadcrumb_size	String	Breadcrumb print size
item_color	String	Display color

Service Layer

ItemService

ItemService implements three interfaces:

Item-specific methods beyond the Data Authority pattern:

Method	Description
supplies(parentEId, time)	List all supplies for an item
createItemSupply(parentEId, supply, time, author, qualifier)	Add a supply source
updateItemSupply(parentEId, supply, time, author, qualifier)	Update a supply source
removeItemSupply(parentEId, supplyEId, time, author)	Remove a supply source
lookupSupplierByName(name, n, asOf)	Typeahead for supplier names
lookupUnit(name, n, asOf)	Typeahead for quantity units
lookupItemByName(name, n, asOf)	Typeahead for item names (returns name + EID)
lookupTypeByName(name, n, asOf)	Typeahead for classification types
lookupSubTypeByName(name, n, asOf)	Typeahead for subtypes
lookupUseCaseByName(name, n, asOf)	Typeahead for use cases
lookupFacilityByName(name, n, asOf)	Typeahead for facilities
lookupDepartmentByName(name, n, asOf)	Typeahead for departments
lookupLocationByName(name, n, asOf)	Typeahead for locations
lookupSublocationByName(name, n, asOf)	Typeahead for sublocations
generateImageUploadCredentials(contentType, contentLength, author)	Presigned S3 POST for image upload

Business rules enforced by the service:

• Item name uniqueness within tenant scope
• Supply reference consistency (supplier EID, name resolution)
• Mutation qualifier enforcement (STRICT, LAX, PROPAGATE)
• Image URL validation (CDN pattern, tenant isolation, HEAD verification)

ItemPrintingService

The printing sub-interface manages template resolution and print job orchestration. It is implemented within ItemService.Impl.

Template resolution methods resolve a size enum to a PrintingTemplateConfiguration (template ID, columns, description). Each falls back to the default size if the requested size is not configured.

Print methods (printLabels, printBreadcrumbs) orchestrate the full printing flow:

1. Deduplicate and validate the input ID list
2. Fetch items from ItemUniverse by record IDs
3. For each item, resolve the template via the size field and render the item to a ItemPrintInfo JSON payload via ItemPrinter
4. Verify all items resolve to the same template (current constraint)
5. Construct a RenderJob with the template configuration and a Grid of item payloads
6. Delegate to PdfRenderService.render() and return the RenderResult

Printing Sequence Diagrams

Print Labels

Print Breadcrumbs

The breadcrumb flow is identical to labels, substituting breadcrumbSize for labelSize in template resolution and POST /item/item-print-breadcrumb as the endpoint path.

Print Labels — Mixed Sizes (Multi-Template Grouping)

When items have different label sizes, the system groups them by template and renders one PDF per group:

Persistence Layer

ItemUniverse

ItemUniverse extends AbstractScopedUniverse<Item, ItemMetadata, ITEM_TABLE, ItemRecord> and provides:

• Standard bitemporal CRUDQ operations (inherited)
• Tenant-scoped queries via ItemUniversalCondition
• Business rule validation via ItemValidator
• Fuzzy-match lookup methods for typeahead fields

Database Tables

Table	Type	Description
ITEM_TABLE (item_bitemporal)	ScopedTable	Main item entity with bitemporal versioning
ITEM_SUPPLY_TABLE (item_supply_bitemporal)	ChildTable (parent: ITEM)	Item supply sources

Composite Persistence Components

The item table uses composite components to map structured value objects to flat database columns:

Component	Maps To	Columns
ItemClassificationComponent	ItemClassification	type, sub_type, use_case, gl_code
PhysicalLocatorComponent	PhysicalLocator	facility, department, location, sub_location
QuantityComponent	Quantity (minQuantity)	amount, unit
ItemSupplyReferenceComponent	ItemSupplyReference (primary, secondary)	supplier_eid, supplier, name, sku, order_method, url, order_quantity_, unit_cost_, lead_time_*

Bitemporal features: effective time, recorded time, entity history, time-travel queries, logical deletion (retired flag).

Configuration

The module is configured at path system.reference.item and reads:

Module Extras

Key	Type	Description
colors.optionsPath	String	Path to color-options.json resource
colors.basePath	String	Path to colors.json resource
frontend.baseUrl	String	Base URL for QR code generation
printTemplatesPath	String	Path to pdf-templates.json resource

Dependencies Injected at Initialization

Dependency	Source	Description
PdfRenderService	shopAccess.pdfRender module	PDF rendering via Documint
BusinessAffiliateService	reference.businessAffiliate module	Supplier reference resolution
Authentication	Component configuration	Request authentication
AwsConfiguration	Component configuration	AWS region, S3 bucket ARNs, presign role ARNs, CDN domain

Resources

Resource	Purpose
reference/item/printing/pdf-templates.json	Template ID, columns, description, active flag per size per material type
reference/item/printing/color-options.json	Available item color values
reference/item/printing/colors.json	Color asset URLs (rectangles, icons) per color value

Item Lookup URL (QR Code)

Printed labels and breadcrumbs embed a QR code that encodes a URL for looking up the item in the UI:

https://{base-url}/item/{eId}/{type}

{type}	Material
0	Label
1	Breadcrumb

Base URLs by Environment

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

The base URL is configured via frontend.baseUrl in the module extras. The eId is the item’s entity ID (available from the Item API at results[*].payload.eId).

When the browser navigates to an item lookup URL, the UI displays the item details for the given eId. If the item is not found, the UI displays an “Item Not Found” message (item never existed, user lacks access, or item was deleted).