Items

The Items model represents reference data for materials, finished products, and any inventory piece that needs to be uniquely identified and managed. It is the central entity that kanban cards represent and purchase order lines reference.

Note on terminology: The terms vendor and supplier are used interchangeably in this document, with a slight preference for vendor. In existing code the term supplier is more prevalent.

Item

An Item is reference data scoped to a tenant, representing a material, finished product, or supply that needs to be identified and managed.

Property	Type	Multiplicity	Description
name	String	[1..1]	Primary name of the item. Business identifier. Not necessarily unique across items in the same tenant.
description	String	[0..1]	Detailed description of the item.
imageUrl	URL	[0..1]	Link to an image representing the item.
classification	ItemClassification	[0..1]	Category or type classification (type + optional subtype).
useCase	String	[0..1]	Recommended or intended usage description.
locator	PhysicalLocator	[0..1]	Default storage or usage location.
internalSKU	String	[0..1]	Company-specific identification code.
minQuantity	Quantity	[0..1]	Minimum stock level or reorder point.
taxable	Boolean	[0..1]	Whether the item is subject to taxes.
primarySupply	ItemSupplyReference	[0..1]	Cached reference to the primary supply source.
secondarySupply	ItemSupplyReference	[0..1]	Cached reference to the secondary (alternate) supply source.
defaultSupply	String	[0..1]	Name of the default supply source.
defaultSupplyEId	UUID	[0..1]	Entity identity of the default supply source.
cardSize	CardSize	[0..1]	Formatting specification for visual kanban cards.
isSupply	Boolean	[1..1]	Whether the item is a supply (consumable).
isProduct	Boolean	[1..1]	Whether the item is a product (saleable).

Invariants

• name is required.
• When either primarySupply or secondarySupply is not null, defaultSupply and defaultSupplyEId must match the name and supplyEId of the non-null value. When both are non-null, they must match one of them.
• When both primarySupply and secondarySupply are null, defaultSupply and defaultSupplyEId must also be null.

ItemSupply

An ItemSupply entity represents a specific way an item can be acquired from a vendor. It is a child record of its parent Item entity — its lifecycle is tied to the parent’s lifecycle.

Property	Type	Multiplicity	Description
vendorEId	UUID	[0..1]	Reference to the vendor’s BusinessRole entity. Null indicates an unknown or unspecified vendor.
vendor	String	[0..1]	Name of the vendor. Must be non-null if vendorEId is non-null, and must match the BusinessAffiliate name.
name	String	[0..1]	Specific name for this supply option. Must be non-null if both vendorEId and vendor are null.
sku	String	[0..1]	Vendor-specific SKU for the item.
orderMethod	OrderMethod	[0..1]	Communication method for placing orders.
url	URL	[0..1]	Direct link to the item on the vendor’s website.
orderQuantity	Quantity	[0..1]	Standard quantity for ordering. Null is interpreted as 0 eaches.
unitCost	Money	[0..1]	Cost per unit of measure. Null is interpreted as 0.00 in the contextual currency.
averageLeadTime	Duration	[0..1]	Expected fulfillment time. Null indicates immediate availability (on-hand).

Invariants

• name must be unique within the set of ItemSupply entities for the same parent Item and the same vendor.
• If vendorEId is not null, it must reference an existing BusinessRole entity with role VENDOR, and vendor must match the associated BusinessAffiliate name.
• If both vendorEId and vendor are null, name must be non-null.

ItemSupplyReference

An ItemSupplyReference is a value object that captures a snapshot or pointer to an ItemSupply. It is used within the Item entity to provide immediate access to supply details without navigating the full supply universe.

Property	Type	Description
supplyEId	UUID	Unique ID of the referenced ItemSupply. If non-null, all other properties must match the referenced entity.
vendorEId	UUID	ID of the vendor’s BusinessRole.
name	String	Name of this supply option.
vendor	String	Name of the vendor.
sku	String	Vendor SKU.
orderMethod	OrderMethod	Communication method for orders.
url	URL	Direct link on vendor’s site.
orderQuantity	Quantity	Standard order quantity.
unitCost	Money	Cost per unit.
averageLeadTime	Duration	Expected fulfillment time.

When supplyEId is null, the reference represents an ad hoc supply option not linked to a persistent ItemSupply entity.

UnitOfMeasure

A UnitOfMeasure is a value scoped to a specific item. Each item defines its own units of measure.

Property	Type	Description
name	String	Unique name for the unit within the item it measures
eaches	Double	How many individual units this measure represents
isBreakable	Boolean	Whether the item can be broken into smaller units
forItem	Reference to Item	The item this unit measures

Quantity

A Quantity is a value object representing an amount of an item with an item-specific unit of measure.

Property	Type	Description
amount	Double	Numerical value of the quantity
unit	String (or UnitOfMeasure ref)	Unit of measure (e.g., kg, each, m)

When Quantity appears as a nullable property, its presence requires both a valid amount (defaulting to 0.0) and a valid unit.

ItemFacility

ItemFacility captures operational information for an item within a specific facility — the handling, receiving, and shipping units, and the minimum quantity maintained at that facility.

Property	Type	Description
item	Reference to Item	The item this record describes
facility	Reference to Facility	The facility this record describes
handlingUnit	UnitOfMeasure	Default unit for representing the item in the facility
receivingUnit	UnitOfMeasure	Unit used when receiving. Defaults to handling unit.
shippingUnit	UnitOfMeasure	Unit used when shipping. Defaults to handling unit.
minimumQty	Quantity	Minimum quantity required of the item in this facility

Supporting Enumerations

OrderMethod

The method used for procurement and fulfillment:

Value	Description
UNKNOWN	Default when the method is not specified
PURCHASE_ORDER	Formal procurement via a PO
EMAIL	Informal ordering via email
PHONE	Informal ordering via telephone
IN_STORE	Direct purchase at a physical location
ONLINE	Purchase via a vendor website
RFQ	Request for Quote process
PRODUCTION	Internal production or manufacturing
TASK	Fulfillment via a task or service
THIRD_PARTY	Sourced from a third-party provider
OTHER	Any other unspecified method

ItemClassification

A value object providing two-level categorization for an item (type and optional subtype). These will be migrated to full category entities in future versions.

Property	Type	Description
type	String	Primary category type
subType	String	Secondary category subtype

Mutation Qualifier Modes

Item mutations through the Item service accept a qualifier that determines how supply source information is interpreted. The three modes are defined in Item Mutation.

Excluded from this document: SQL table schemas, Kotlin class names, and detailed service method signatures (e.g., ItemService.create, ItemService.update) belong in the Current System section.