Entities and Relationships

This page describes the core data entities in the Lucid Green platform and how they relate to each other.

Entity Hierarchy

The primary entities form a hierarchy from Brand down to individual Item:

Brand
├── Product (many per Brand)
│   └── Batch (many per Product)
│       ├── Digital COA (one or more per Batch)
│       └── Item / LucidID (many per Batch)
│           └── Collections (many per Item)

• A Brand represents a cannabis producer or manufacturer.

• A Product is a specific SKU offered by a Brand (e.g., “Blue Dream 3.5g Flower”).

• A Batch is a production run of a Product, identified by a regulatory ID (such as a Metrc tag).

• A Digital COA (Certificate of Analysis) contains lab test results for a Batch.

• An Item is a single physical unit, uniquely identified by a LucidID QR code.

• Collections are groupings of Items used for tracking, compliance, and fulfillment.

Brands, Products, and Batches

Each Brand can have multiple Products. Products are linked to their Brand via brand_uuid.

Each Batch represents a specific production lot. Batches are linked to a Brand via brand_uuid and are associated with a regulatory_id (e.g., a Metrc batch tag). A Batch may have one or more Digital COAs attached, referenced via digital_coa_uuids.

Items and LucidIDs

An Item is the most granular entity — it represents a single physical product unit. Every Item has a unique LucidID, a 22-character UUID that is encoded as a QR code on the product packaging.

Each Item is linked to exactly one Brand, Product, and Batch:

Field	Relationship
brand_uuid	The Brand that produced this item
product_uuid	The Product SKU for this item
batch_uuid	The Batch (production run) this item belongs to

Items also track their Collection memberships via the collections array, and their lab results via digital_coa_uuids.

Collections

Collections are the primary mechanism for grouping and tracking Items throughout the supply chain. An Item can belong to any number of Collections simultaneously — adding an Item to a new Collection does not remove it from existing ones.

Collection Types

Type	Purpose	Example
case	A physical case or shipment of items, identified by a CaseID QR code	A case of 24 units shipped to a distributor
regulator	A regulatory or Metrc tag assignment	Metrc batch tag 1A406030000B5C7000001234
container	A storage container or bin	Warehouse bin B-14
order	An ERP or POS order	Order ORD-2025-0042
package	A generated CaseID for order fulfillment	CaseID sticker for a pick-and-pack order
origin	Permanent source/origin record (cannot be removed)	Original manufacturing origin

How Collections Work

Each Collection has:

• A uuid — unique identifier

• An identifier — human-readable label (e.g., a Metrc tag number or internal case ID)

• A collection_type — one of the types listed above

• An items array — the Items belonging to this Collection, each with an added_on timestamp

Collections are “append-only” by design: the full history of an Item’s Collection memberships serves as a provenance record for that physical unit.

Regulatory IDs and Collections

Regulatory IDs (Metrc tags) are stored as Collections with collection_type="regulator". An Item can have multiple regulatory IDs over its lifecycle — for example, when product is relabeled or transferred between licensees. The most recent regulatory ID is determined by the added_on timestamp.

Items reference their regulatory ID collections via regulator_id_uuids, and their case collections via cases_uuids.

Digital COAs

A Digital COA (Certificate of Analysis) contains the laboratory test results for a Batch. Each COA includes:

• The Testing Laboratory that performed the analysis

• Test results for cannabinoids, terpenes, pesticides, heavy metals, mycotoxins, microbials, residual solvents, and other categories

• Totals for THC, CBD, total cannabinoids, and total terpenes

• Pass/fail status for each test category

Digital COAs are linked to Batches and can also be referenced directly from Items via digital_coa_uuids.

LucidSource vs. LucidRetail

The same entities appear in both products, but with different contexts:

	LucidSource	LucidRetail
Purpose	Supply chain management and compliance	Point-of-sale integration and consumer activation
Primary users	Brands, distributors	Dispensaries, retailers
Item creation	Creates and manages Items/LucidIDs	Receives Items via case webhooks
Collections	Full CRUD on all collection types	Primarily receives cases, manages inventory
Transactions	N/A	Records retail sales via retail_transactions_create
Additional fields	N/A	is_paired, is_claimed, dispensary_uuid on Items

In a typical workflow, a Brand uses LucidSource to create Items, assign them to Batches and Collections, and ship cases to retailers. The retailer’s POS system uses LucidRetail to receive those cases, scan Items at checkout, and submit transaction records.