Catalog - Structural Topology & Domain Model
Tactical domain modeling, aggregate root boundaries, dynamic attribute family schemas, multi-tree taxonomies, and BOM recipe graphs for the Catalog (PIM) domain (obelaw/ium-catalog).
The structural topology of the Catalog domain (obelaw/ium-catalog) defines the tactical arrangement of catalog entities, value objects, and aggregate boundaries. In accordance with Vlad Khononov’s Learning Domain-Driven Design, aggregates serve as transactional consistency boundaries, ensuring that internal invariant rules remain intact under concurrent modifications.
1. Tactical Modeling: Aggregate Roots & Boundaries
The Catalog bounded context is organized around five primary Aggregate Roots. Each aggregate encapsulates its internal entity graph and exposes explicit domain operations:
flowchart TD
subgraph AR_Product["Product Aggregate Root (SPU)"]
SPU["Parent Product Entity<br/>Handle, Brand, Master Category"]
Options["Option Type Bindings<br/>Size, Color, Capacity"]
SKUs["Child Variant Entities (SKUs)<br/>Barcode, Weight, Dimensions"]
Media["Asset Attachment Links<br/>Role: hero, gallery, swatch"]
AttrValues["Scoped Attribute Values<br/>Channel + Locale Values"]
SPU --> Options
SPU --> SKUs
SPU --> Media
SPU --> AttrValues
end
subgraph AR_Family["Attribute Family Aggregate Root"]
AF["Attribute Family Entity"]
Groups["Attribute Groups"]
Attrs["Attribute Definitions & Validation Rules"]
AF --> Groups --> Attrs
end
subgraph AR_Category["Category Tree Aggregate Root"]
Tree["Category Tree Entity<br/>Master vs Merchandising"]
Nodes["Hierarchical Category Nodes"]
Tree --> Nodes
end
subgraph AR_BOM["Bill of Materials Aggregate Root"]
BOM["BOM Header Entity<br/>Finished SKU, Revision Code"]
Comp["Component Line Items<br/>Quantity, Scrap %"]
BOM --> Comp
end
subgraph AR_Channel["Channel Syndication Aggregate Root"]
Channel["Sales Channel Entity"]
Locales["Permitted Locales"]
Gates["Completeness Criteria Rules"]
Channel --> Locales
Channel --> Gates
end
AR_Family -.->|"Schema Definition"| AR_Product
AR_Category -.->|"Classification"| AR_Product
AR_Product -.->|"Finished Assembly"| AR_BOM
AR_Channel -.->|"Readiness Validation"| AR_Product
Aggregate Boundary Definitions
| Aggregate Root | Encapsulated Entities & Objects | Consistency Responsibility & Invariant Scope |
|---|---|---|
| Product (SPU) | Product SPU, Child Variant SKUs, Option Types, Option Values, Asset Attachments, Localized Attribute Values. | Enforces variant option uniqueness, prevents orphan SKUs, manages lifecycle state changes, and coordinates completeness evaluations. |
| Attribute Family | Family Definition, Attribute Groups, Attribute Configurations, Type Constraints, Unit Bindings. | Guarantees attribute code uniqueness, enforces data type schemas, and manages structural template revisions without altering database tables. |
| Category Tree | Category Tree Definition, Category Nodes, Hierarchy Paths, Channel Linkages. | Enforces tree acyclicity, guarantees parent-child node integrity, and validates single-parent constraints for the Master Taxonomy. |
| Bill of Materials (BOM) | BOM Header, Revision Tag, Component Lines, Quantity Requirements, Scrap Ratios. | Enforces acyclic assembly graphs ($P_A \notin \text{Descendants}(P_A)$), mandates positive component quantities, and guarantees immutability upon approval. |
| Channel Syndication | Channel Entity, Enabled Locales, Mandatory Attribute Lists, Asset Resolution Criteria. | Evaluates publication readiness, calculates completeness percentages, and maintains channel-specific validation rules. |
2. Entities vs. Value Objects
A foundational DDD tenet is segregating mutable entities (defined by continuous identity) from immutable value objects (defined strictly by their structural attributes):
| Domain Construct | Tactical Type | Mutability | Structural Representation & Invariant Characteristics |
|---|---|---|---|
| Product (SPU) | Entity | Mutable | Defined by a persistent handle and product ID. State transitions follow an explicit lifecycle. |
| Product Variant (SKU) | Entity | Mutable | Defined by its internal variant identity, but its natural SKU code becomes permanently locked once transacted. |
| SkuCode | Value Object | Immutable | Formatted, alphanumeric string adhering to standardized enterprise SKU naming conventions. |
| GtinBarcode | Value Object | Immutable | Optical string validated against GS1 Modulo 10 check-digit algorithms (EAN-13, UPC-A, GTIN-14). |
| DimensionSet | Value Object | Immutable | Encapsulates length, width, height, and unit of measure: { length: 35.0, width: 28.0, height: 5.0, unit: "cm" }. |
| WeightMetric | Value Object | Immutable | Encapsulates gross physical mass: { value: 480.0, unit: "g" }. Negative values are mathematically rejected. |
| MonetaryAmount | Value Object | Immutable | Currency code and decimal amount: { amount: 450.00, currency: "USD" }. |
| CompletenessVector | Value Object | Immutable | Ratio of fulfilled vs required criteria: { channel: "web", locale: "en-US", score: 1.0, missing: [] }. |
| ScrapRate | Value Object | Immutable | Percentage allowance bounded strictly between zero and one: $0.0 \le S < 1.0$. |
3. Product & Variant Structural Hierarchy
The catalog foundation separates the conceptual product from concrete physical variants:
Product (SPU) - "Mountain Apex Technical Jacket"
├── Brand: "Apex Outdoors"
├── Master Taxonomy Leaf: Apparel > Outerwear > Jackets > Technical Shells
├── Attribute Family: "Technical Apparel Schema"
│ ├── Material: 3-Layer GORE-TEX Pro Shell
│ ├── Waterproof Rating: 28,000 mm
│ └── Breathability: 25,000 g/m²/24h
├── Shared Media: Hero Campaign Photography, Brand Video
├── Base List Price: $450.00 USD
├── Option Axes: [Color, Size]
└── Child Variants (SKUs)
├── Variant SKU: APEX-BLK-M
│ ├── Option Values: Color = Black, Size = Medium
│ ├── Barcode (GTIN-13): 0793573194012
│ ├── Packaged Dimensions: 35cm x 28cm x 5cm | Gross Weight: 480g
│ ├── Variant Price Override: null (inherits base $450.00 USD)
│ └── Specific Media: Black Colorway Swatch & Model Images
├── Variant SKU: APEX-BLK-L
│ ├── Option Values: Color = Black, Size = Large
│ ├── Barcode (GTIN-13): 0793573194029
│ ├── Packaged Dimensions: 37cm x 30cm x 5cm | Gross Weight: 510g
│ ├── Variant Price Override: null (inherits base $450.00 USD)
│ └── Specific Media: Black Colorway Swatch & Model Images
└── Variant SKU: APEX-RED-M
├── Option Values: Color = Solar Red, Size = Medium
├── Barcode (GTIN-13): 0793573194036
├── Packaged Dimensions: 35cm x 28cm x 5cm | Gross Weight: 480g
├── Variant Price Override: null (inherits base $450.00 USD)
└── Specific Media: Red Colorway Swatch & Model Images
Responsibility Split: Product SPU vs. Variant SKU
| Operational Dimension | Product SPU Level | Variant SKU Level |
|---|---|---|
| Identity & Slugs | Global handle, SEO friendly slug, marketing title. | SKU code, optical GTIN/EAN barcode, internal part number. |
| Imagery & Assets | Brand campaign lookbooks, technology diagrams. | Colorway swatches, package photos, angle-specific imagery. |
| Pricing Model | Baseline catalog MSRP, default list price. | Variant price overrides (surcharges for premium sizes/materials). |
| Logistics Specs | Broad freight classification (e.g., standard parcel). | Exact packaged length, width, height, gross weight, and base UOM. |
| Operational Execution | None (abstract marketing grouping). | Warehouse bin storage, POS scanning, sales order line fulfillment. |
4. Dynamic Attribute Family & Schema Topology
Catalog supports diverse product categories without requiring ongoing database schema modifications. The dynamic schema engine organizes attributes into structured families:
flowchart TD
AF["Attribute Family<br/>e.g., Technical Apparel Schema"]
G1["Attribute Group: Performance"]
G2["Attribute Group: Material & Care"]
G3["Attribute Group: Logistics"]
A1["Attribute: Waterproof Rating (Unit Metric)"]
A2["Attribute: Windproof Rating (Boolean)"]
A3["Attribute: Fabric Composition (Text)"]
A4["Attribute: Country of Origin (Choice Code)"]
AF --> G1
AF --> G2
AF --> G3
G1 --> A1
G1 --> A2
G2 --> A3
G3 --> A4
Supported Attribute Data Types
| Data Type | Description | Value Schema Example | Invariant Validation & Boundaries |
|---|---|---|---|
| Text / String | Single-line alphanumeric string. | "GORE-TEX Pro 3L" | Regex patterns, min/max length constraints. |
| Rich Text | Multi-line formatted markdown or HTML. | "<p>Engineered for alpine conditions...</p>" | Tag whitelisting, prohibited script tags. |
| Numeric | Integer or decimal numbers. | 28000 | Min/max numerical boundaries, step intervals. |
| Unit Metric | Numeric value bound to a unit of measure. | { "value": 28000, "unit": "mm" } | Unit must exist within the global Unit Registry. |
| Boolean | Binary true/false flag. | true | Strict boolean literal (no null if mandatory). |
| Date / Time | Specific calendar date or ISO timestamp. | "2026-10-01" | ISO-8601 formatting, chronological validity. |
| Single Choice | Discrete selection from a predefined set. | "hardshell_jacket" | Code must match an active attribute option choice. |
| Multi Choice | Multiple selections from a predefined set. | ["waterproof", "breathable", "windproof"] | Subset check against approved attribute choices. |
| Media Ref | Pointer to a centralized digital asset. | "uuid:asset-9042-tech" | File type and resolution conformance. |
5. Multi-Channel & Multi-Locale Scoping Topology
Enterprises sell globally across varied storefronts and regional markets. Attribute resolution adheres to an explicit four-tier fallback cascade:
flowchart TD
Query["Attribute Resolution Request<br/>(Entity, Attribute, Channel, Locale)"] --> C1{"Specific Channel & Specific Locale<br/>Defined?"}
C1 -->|Yes| R1["Return: Channel + Locale Value"]
C1 -->|No| C2{"Specific Channel & Default Locale<br/>Defined?"}
C2 -->|Yes| R2["Return: Channel + Default Locale Value"]
C2 -->|No| C3{"Global Scope & Specific Locale<br/>Defined?"}
C3 -->|Yes| R3["Return: Global + Locale Value"]
C3 -->|No| C4{"Global Scope & Default Locale<br/>Defined?"}
C4 -->|Yes| R4["Return: Global Default Value"]
C4 -->|No| R5["Return: Null / Missing Attribute Error"]
Scoping Matrix Resolution Examples
| Attribute Code | Scoping Level | Web Store (en-US) | Web Store (ar-SA) | Retail POS (en-US) | Marketplace (en-US) |
|---|---|---|---|---|---|
sku_code | Global (Non-Translatable) | APEX-BLK-M | APEX-BLK-M | APEX-BLK-M | APEX-BLK-M |
title | Channel + Locale Scoped | Men’s Apex Jacket | جاكيت أبيكس للرجال | Apex Mns Jkt | Men’s Apex Waterproof Alpine Shell Jacket |
short_desc | Channel + Locale Scoped | Lightweight alpine shell | سترة خفيفة مقاومة للماء | Display: Apex M | High-performance GORE-TEX waterproof jacket |
gross_weight | Global (Physical Spec) | 480g | 480g | 480g | 480g |
list_price | Channel Scoped | $450.00 USD | 1,690.00 SAR | $450.00 USD | $439.99 USD |
6. Multi-Tree Category Taxonomy Topology
To support rigid financial reporting alongside fluid digital marketing, Catalog isolates Master Taxonomies from Merchandising Navigation Trees:
flowchart TD
subgraph Master_Taxonomy["Master Taxonomy (Single-Parent, Strict Rollup)"]
M1["Root: Enterprise Merchandise"] --> M2["Division: Apparel"]
M2 --> M3["Category: Outerwear"]
M3 --> M4["Leaf: Technical Shells (Canonical Node)"]
end
subgraph Merchandising_Trees["Merchandising Trees (Multi-Parent, Flexible Discovery)"]
W1["Web Navigation Tree"] --> W2["Men's New Arrivals"]
W1 --> W3["Mountaineering Expedition Gear"]
S1["Seasonal Campaign Tree"] --> S2["Winter Clearance: Shells Under $500"]
end
Product["Product: Apex Technical Jacket"]
Product ===|1 : 1 Mandatory Link| M4
Product -.->|Flexible Association| W2
Product -.->|Flexible Association| W3
Product -.->|Flexible Association| S2
Structural Taxonomy Constraints
- Strict Single-Parent Assignment: Every active product must be assigned to exactly one leaf node within the Master Taxonomy. Parent node assignment is prohibited.
- Multi-Parent Merchandising Associations: Products may be projected into multiple marketing trees and seasonal categories without impacting master corporate reporting.
7. Digital Asset Management (DAM) Attachment Topology
Digital assets are stored in a centralized asset repository and associated with catalog entities through role-based attachment links:
flowchart LR
Asset["Centralized Asset Library<br/>UUID, MimeType, Checksum"]
Link["Attachment Relationship Link"]
Asset --> Link
Link -->|Scope: Global, Role: hero_image| Product["Parent Product (SPU)"]
Link -->|Scope: Global, Role: tech_sheet| Product
Link -->|Scope: Variant, Role: swatch_icon| VariantBlack["Variant: APEX-BLK-M"]
Link -->|Scope: Variant, Role: packshot| VariantBlack
| Asset Role Code | Attached Entity | Permitted Formats | Structural Business Purpose |
|---|---|---|---|
hero_image | Product (SPU) | WebP, AVIF, JPEG | Primary thumbnail and detail hero image across digital storefronts. |
gallery_image | Product / Variant | WebP, AVIF, JPEG, PNG | Multi-angle detail views and lifestyle imagery in product media galleries. |
swatch_icon | Variant (SKU) | SVG, WebP, PNG | Compact visual preview representing specific colors, patterns, or materials. |
tech_sheet | Product (SPU) | Downloadable technical datasheet and regulatory specification document. | |
safety_sds | Product (SPU) | Mandatory Safety Data Sheet (SDS) for hazardous or regulated chemical goods. | |
cad_model | Product (SPU) | STEP, IGES, GLTF | 3D dimensional model for engineering integration and AR viewing. |
8. Bill of Materials (BOM) & Assembly Recipe Graph
For products assembled internally or via manufacturing partners, Catalog models an engineering recipe as a Directed Acyclic Graph (DAG):
flowchart TD
FG["Finished Good SKU: APEX-BLK-M<br/>BOM Revision: Rev B (Approved)"]
C1["Fabric: GORE-TEX 3L Black<br/>SKU: RAW-FAB-001<br/>Gross Qty: 2.4 m | Scrap: 3.5%"]
C2["Zipper: Waterproof 75cm<br/>SKU: RAW-ZIP-075<br/>Gross Qty: 1.0 pc | Scrap: 0.0%"]
C3["Tape: Seam Sealing 20mm<br/>SKU: RAW-TAP-020<br/>Gross Qty: 0.1 kg | Scrap: 2.0%"]
C4["Embroidered Logo Patch<br/>SKU: RAW-LBL-004<br/>Gross Qty: 1.0 pc | Scrap: 0.0%"]
FG --> C1
FG --> C2
FG --> C3
FG --> C4
BOM Topological Constraints
- Strict Acyclicity (DAG): The recipe graph must be acyclic. An assembly can never contain itself as a sub-assembly, directly or transitively: $P_A \notin \text{Descendants}(P_A)$.
- Component Atomicity: Every component line item points to an active raw material SKU or sub-assembly SKU with an explicit positive quantity ($Q > 0$).
- Revision Immutability: Once an engineering revision reaches the
Approvedstate, all constituent component lines and scrap rates are permanently locked.
9. Concrete Database Schema & Eloquent Architecture (obelaw/ium-catalog)
All persistence tables in obelaw/ium-catalog are prefixed with obelaw_catalog_:
| Table Name | Eloquent Model | Key Columns & Relationships |
|---|---|---|
obelaw_catalog_products | Product | sku (unique), barcode (unique GS1 GTIN), name, description, status (ProductStatus), superseding_sku, uom_id, published_at, deprecated_at, softDeletes |
obelaw_catalog_product_variants | ProductVariant | product_id, sku (unique), barcode (unique GS1 GTIN), name, is_active, price_override, weight, length, width, height, softDeletes |
obelaw_catalog_attributes | Attribute | code (unique), name, type (text, number, boolean, select), is_required, is_filterable |
obelaw_catalog_attribute_values | AttributeValue | attribute_id, value (lookup options for select attributes) |
obelaw_catalog_product_attribute_values | ProductAttributeValue | product_id, attribute_id, value |
obelaw_catalog_product_variant_attribute_values | ProductVariantAttributeValue | product_variant_id, attribute_id, value |
obelaw_catalog_categories | Category | parent_id (self-referencing tree), name, slug (unique), is_active, position |
obelaw_catalog_category_product | (Pivot) | category_id, product_id |
obelaw_catalog_media | Media | mediable_type, mediable_id (morphs to Product/ProductVariant), file_path, file_type, asset_role (AssetRole), position, is_primary |
obelaw_catalog_unit_of_measures | UnitOfMeasure | code (unique, e.g. PCS, BOX), name, symbol |
obelaw_catalog_uom_conversions | UomConversion | from_uom_id, to_uom_id, factor (decimal 14,6) |
obelaw_catalog_price_lists | PriceList | name, currency (ISO-4217), is_active, priority |
obelaw_catalog_prices | Price | price_list_id, priceable_type, priceable_id (morphs), price, special_price, special_price_from, special_price_to |
obelaw_catalog_product_stocks | ProductStock | stockable_type, stockable_id (morphs), physical_quantity, reserved_quantity |
obelaw_catalog_boms | Bom | product_id, code (unique), version, status (BomStatus), is_active, approved_at |
obelaw_catalog_bom_components | BomComponent | bom_id, component_type, component_id (morphs), quantity, uom_id, scrap_factor, position |
Shared Polymorphic Traits & Data Transfer Objects (DTOs)
- Polymorphic Model Traits (
Obelaw\Ium\Catalog\Traits\*):HasMedia: Attachesmedia(),primaryImage(),videos(), andmanuals()to bothProductandProductVariant.HasPrices: Attachesprices()to bothProductandProductVariant, evaluated viaium()->catalog()->priceResolver()->resolve($entity, $priceListId).HasStock: Attachesinventory(),getPhysicalStock(),getReservedStock(), andgetAvailableStock()to bothProductandProductVariant.
- Immutable DTOs (
Obelaw\Ium\Catalog\Data\*):ProductDTO,VariantDTO,MediaDTO,OptionMatrixData,CompletenessReport,BomData, andBomComponentDataenforce strict type safety at the boundary between UIs/Controllers and the domain services.