Item Module

Status: Live. This module is built and running. The full engineering reference for what ships today — every route, service, and persistence detail — is kept at Item (Q2 2026).

Purpose

An Item is the catalog entry for a kind of stock — the product or SKU that the operational parts of the system point at. Inventory holdings, kanban cards, and order lines all refer to an item; the item itself is reference data (a description of a kind of thing), not a physical holding of it. The module is the single place a tenant defines what it buys, makes, stocks, and sells.

Main entities

An item owns a set of supply sources — each one a way to obtain the item from a supplier, with its ordering terms — and may carry a units-of-measure scheme that decides how its quantities behave.

• Item — the catalog entry: a name, an optional classification, an optional reorder threshold, and a location. An item may designate a primary and secondary supply as its preferred sources.
• Item supply — one way to source the item: which supplier provides it, under what SKU, by what ordering method, in what order quantity, at what unit cost, with what lead time. An item can have several.
• Supplier reference — how a supply names its supplier: a name plus a soft link to a vendor role in the Business Affiliate module (see that module for how vendor references stay fresh).
• Units-of-measure scheme — an optional set of units with conversions to a common base unit. An item that carries one is inventory-tracked; an item without one is non-tracked. This is the pivotal distinction: tracked items support exact quantity arithmetic (min/max, “full”, zero checks) because every unit converts to a common base; non-tracked items accept any unit but can only be compared loosely.

Operations

Action	What it does	When it is allowed
Create / update / delete	Standard management of an item, with full history kept and drafts supported.	Any time.
Query / look up	Filter and page through items; typeahead lookups for names, suppliers, units, classifications, and locations.	Any time.
Manage supplies	Add, edit, and remove an item’s supply sources; each resolves its supplier to a vendor.	Any time.
Print	Produce labels and breadcrumbs (with QR codes) for one or more items.	Any time.
Upload image	Attach a product image.	Any time.

Guarantees

• Item names are unique within a tenant. Two items can’t share a name in the same tenant.
• A supply belongs to exactly one item. Supplies are never shared between items.
• Preferred supplies are distinct. An item’s primary and secondary supply must be two different supplies.
• Supplier references stay honest. Every supply resolves its supplier to a vendor (reusing an existing vendor, or creating one). When a vendor is renamed the change flows in; when a vendor is removed the supply is marked stale rather than silently broken (handled with the Business Affiliate module).
• Inventory-tracking is fixed at the item. Whether an item is inventory-tracked is decided by whether it carries a units-of-measure scheme, and does not flip underneath its holdings.

How it relates to its neighbors

• Business Affiliate — supply sources name their supplier through a vendor reference resolved there.
• Kanban Cards — each card represents an item and keeps a lightweight reference to it.
• Inventory Item — on-hand holdings are holdings of an item.
• Orders — an order line orders a specific item.