Catalog - Introduction & Executive Overview
High-level architectural overview of the Catalog (PIM) domain module (obelaw/ium-catalog), exploring business drivers, operational challenges, and strategic value.
Catalog (PIM) Domain Design
Managing product information is one of the most complex architectural challenges in omnichannel commerce and industrial manufacturing. In modern enterprises, merchandise data is touched by nearly every business discipline: creative copywriters author localized storytelling, studio photographers produce digital media, packaging engineers measure physical dimensions, compliance officers verify safety data sheets, and manufacturing teams maintain multi-level assembly recipes.
The Catalog domain—implemented by obelaw/ium-catalog—functions as the single, authoritative home for all enterprise merchandise definitions. Serving as the Product Information Management (PIM) core in Obelawium ERP, it governs master catalog hierarchies, variant option matrices, extensible dynamic attribute schemas, multi-tree classification taxonomies, role-based digital asset associations, multi-channel syndication readiness, and engineering Bills of Materials (BOM).
By establishing a dedicated, sovereign Bounded Context, catalog data remains cleanly decoupled from high-volume transactional engines—such as warehouse bin allocation, retail POS scanner checkout, commercial sales quote execution, and double-entry accounting ledgers.
1. Business Drivers & The Catalog Chaos Problem
When organizations operate without an isolated Catalog / PIM domain, product information rapidly degenerates into architectural chaos:
flowchart TD
subgraph Antipattern["Without Catalog Domain: Architectural Coupling & Chaos"]
FatDB["Overloaded Relational Database<br/>Marketing copy, stock balances, register prices & supplier notes tangled in single tables"]
LooseVariants["Loose Text Options<br/>Misspelled sizes and colors causing duplicate SKUs and shipping errors"]
PrematurePublish["Unvalidated Product Launches<br/>Incomplete items syndicated with missing images and translations"]
SchemaChurn["Continuous Migration Churn<br/>New product types forcing constant database migrations and schema downtime"]
end
subgraph Solution["With Catalog Domain: Strict Domain-Driven Architecture"]
Catalog["Catalog Bounded Context (ium-catalog)<br/>Canonical Master Hub & Dynamic Schemas"]
Gates["100% Completeness Publication Gates"]
Matrix["Combinatorial Collision-Free Variant Matrix"]
CleanEvents["Asynchronous Domain Events to WMS, OMS, POS & MRP"]
end
Antipattern -.->|Solved By Domain-Driven Design| Solution
The Cost of Catalog Entropy
- Overloaded Data Stores: Single database tables frequently attempt to store localized marketing prose, physical package dimensions, barcode strings, contractual discount rates, and vendor lead times. This leads to severe query contention, bloated indexes, and operational fragility.
- Variant Option Collisions: Storing size and color options as unstructured free-form text strings inevitably results in spelling variations (e.g., “Navy”, “Navy Blue”, “Dark Navy”), duplicate SKUs, and picking errors in fulfillment centers.
- Schema Rigidity & Migration Churn: Introducing a new merchandise category (such as footwear, fine jewelry, or industrial electronics) forces engineering teams to alter database schemas or resort to unindexed, unvalidated JSON blobs.
- Premature Commercial Publication: In the absence of automated readiness gates, products lacking primary photography, certified dimensions, or mandatory regulatory translations get published accidentally, frustrating consumers and triggering costly shipment returns.
Applying strategic and tactical Domain-Driven Design (DDD) resolves these failure modes by giving merchandise data its own formal boundaries, invariant rules, and operational lifecycles.
2. Core Strategic Pillars of the Catalog Domain
The Catalog bounded context is constructed upon seven foundational architectural pillars:
flowchart TD
Catalog["Catalog Domain Core (ium-catalog)"]
P1["1. SPU vs. SKU Distinction<br/>Marketing Shells separated from Sellable Items"]
P2["2. Dynamic Attribute Families<br/>Extensible Typed Schemas without Schema Alteration"]
P3["3. Multi-Tree Taxonomies<br/>Master Reporting Tree isolated from Merchandising"]
P4["4. Scoping & Fallback Cascade<br/>Channel and Locale resolution across 4 Tiers"]
P5["5. Zero-Tolerance Completeness Gates<br/>100% Quality Verification before Syndication"]
P6["6. Engineering BOM Recipes<br/>Acyclic Directed Graphs with Scrap Tolerances"]
P7["7. Immutable Auditability<br/>Append-Only Logging & Compensating Rollbacks"]
Catalog --> P1
Catalog --> P2
Catalog --> P3
Catalog --> P4
Catalog --> P5
Catalog --> P6
Catalog --> P7
1. Separation of Products (SPU) from Variants (SKU)
Catalog enforces a clean distinction between the abstract merchandise concept (Standard Product Unit - SPU) and the concrete, physical item customers purchase (Stock Keeping Unit - SKU). The SPU holds brand equity, core descriptions, master taxonomy placement, and shared lookbooks. The SKU holds physical attributes: specific option values (Navy / Large), optical GTIN barcodes, packaged dimensions, and gross mass.
2. Extensible Attribute Family Engine
Different merchandise categories demand radically different specifications. A laptop requires processor architectures and RAM speeds, whereas technical outerwear demands waterproof ratings and membrane breathability. Catalog employs dynamic Attribute Families to enforce strongly-typed validation rules without modifying relational database schemas.
3. Dual-Taxonomy Architecture
Catalog isolates the single-parent Master Reporting Taxonomy (mandated by corporate finance and statutory classification) from flexible, multi-parent Merchandising Trees (tailored for digital menus, search navigation, and seasonal campaigns).
4. Multi-Channel & Multi-Locale Fallback Cascade
Global enterprises sell across varied digital storefronts, B2B portals, and brick-and-mortar stores. Catalog resolves marketing copy and display titles through a deterministic four-tier cascade: Channel + Locale $\to$ Channel + Default Locale $\to$ Global + Locale $\to$ Global Default.
5. Zero-Tolerance Publication Gates
A catalog item cannot go live on an external commercial channel until its calculated completeness vector reaches exactly 100%. If an item lacks mandatory translations, required technical specifications, or certified hero imagery, publication is strictly aborted.
6. Engineering Bill of Materials (BOM) Formulation
For assembled finished goods, commercial bundles, and subcontracted items, Catalog models assembly recipes as Directed Acyclic Graphs (DAGs). Recipes specify raw materials, sub-assemblies, gross quantities, and scrap allowances, and are locked permanently upon formal engineering approval.
7. Continuous Auditability & Compensating Rollbacks
Catalog modifications are recorded in an append-only audit trail capturing microsecond timestamps, actor identities, origin sources, and structural diffs. Accidental batch errors (such as flawed bulk spreadsheet imports) are corrected via inverse compensating transactions rather than destructive database rollbacks.
3. High-Level Inter-Domain Choreography
The Catalog bounded context operates as the upstream catalog authority within the enterprise ecosystem. It broadcasts domain events when merchandise definitions reach validated milestones:
flowchart TD
Catalog["Catalog Bounded Context<br/>Canonical Catalog & Engineering Recipes"]
WMS["Inventory / WMS<br/>Stock & Warehousing"]
OMS["Sales / OMS<br/>Order Validation & Pricing"]
POS["Point of Sale (POS)<br/>Frontline Checkout"]
MRP["Manufacturing / MRP<br/>Work Orders & Assembly"]
Channels["Digital Channels & Edge CDN<br/>Search & Storefronts"]
Catalog -->|"VariantCreated, VariantUpdated"| WMS
Catalog -->|"ProductPublished, ProductDeprecated"| OMS
Catalog -->|"VariantBarcodeAssigned, Snapshots"| POS
Catalog -->|"BOMRevisionApproved"| MRP
Catalog -->|"ProductPublished, ChannelSyndicated"| Channels
| Integrating Context | Received Catalog Event | Operational Materialization in Downstream Context |
|---|---|---|
| Inventory / WMS | VariantCreated / VariantUpdated | Instantiates warehouse master items, configures bin allocation profiles, and logs gross package dimensions. |
| Sales / Order Management | ProductPublished / ProductDeprecated | Refreshes sellable catalog search snapshots, enforces active order line validations, and flags discontinued items for sell-down. |
| Point of Sale (POS) | VariantBarcodeAssigned | Ingests optical barcode mappings into local in-memory scanner lookup tables to support low-latency offline checkout. |
| Manufacturing / MRP | BOMRevisionApproved | Binds immutable assembly recipes to shop floor work orders, material requirement planning, and subcontracting dispatch ratios. |
| Storefronts & Channels | ProductPublished / ChannelSyndicated | Formats denormalized search documents, flushes edge CDN caches, and refreshes public web and mobile discovery indexes. |
4. Architectural Domain Blueprint Structure
Explore the comprehensive technical specifications and tactical design models across the following blueprint chapters:
- Bounded Context & Strategic Domain Classification: Strategic domain type, operational scope, out-of-scope boundaries, context mapping, and Anti-Corruption Layer (ACL) architecture.
- Ubiquitous Language & Domain Glossary: Canonical business vocabulary, cross-context linguistic boundary translations, and essential conceptual distinctions.
- Structural Topology & Domain Model: Tactical aggregate roots, entity hierarchies, dynamic attribute family schemas, multi-tree taxonomies, and BOM graph models.
- Domain Invariants & Business Rules (“The Law”): Non-negotiable enterprise constraints, global SKU and optical barcode uniqueness, option collision prevention formulas, completeness gates, and BOM acyclicity rules.
- Operational Workflows & State Machines: Finite state machines for product lifecycles, variant matrix generation pipelines, channel publication workflows, and comprehensive transition matrices.
- Domain Events & Integration Contracts: Authoritative catalog of emitted domain events, downstream integration contracts, and asynchronous event choreography.
- Audit Trail, Governance & Reconciliation Strategies: Immutable append-only audit logging, snapshot-based versioning, superseding SKU sunsetting protocols, and compensating transaction recovery.
5. Reference Implementation (obelaw/ium-catalog)
In the Obelawium ecosystem, the Catalog (PIM) bounded context is implemented by the obelaw/ium-catalog package and registered on the central ium() gateway under the catalog domain key (Ium::registerDomain('catalog', CatalogDomain::class)), with backward-compatible aliases for pim.
All interactions—whether from Admin UIs (Filament / Livewire), Storefront controllers, POS barcode terminals, or downstream ERP modules—are executed through the fluent ium()->catalog() DSL:
| Gateway Accessor | Concrete Class | Responsibility |
|---|---|---|
ium()->catalog()->products() | ProductRepository | Master Product & ProductVariant persistence, SKU/GS1 Barcode lookups, and published catalog queries |
ium()->catalog()->categories() | CategoryRepository | Hierarchical Category taxonomy management and slug resolution |
ium()->catalog()->variantMatrix() | VariantMatrixService | Cartesian product generation of ProductVariant records across up to 3 select option axes |
ium()->catalog()->completeness() | CompletenessService | Channel readiness evaluation (CompletenessReport scoring 0.0–100.0) and pre-publication gate enforcement |
ium()->catalog()->lifecycle() | ProductLifecycleService | Governed state transitions (DRAFT $\to$ ENRICHMENT $\to$ REVIEW $\to$ PUBLISHED $\to$ DEPRECATED $\to$ ARCHIVED) |
ium()->catalog()->priceResolver() | PriceResolverService | Multi-currency PriceList evaluation, promotional window checks, and variant-to-parent price fallback |
ium()->catalog()->stockManager() | StockManagerInterface | Pluggable inventory strategy (CatalogStockManager default or WmsStockManager adapter) for physical, reserved, and ATP stock |
ium()->catalog()->uomConverter() | UomConverter | Deterministic dimensional conversion across UnitOfMeasure definitions (obelaw_catalog_uom_conversions) |
ium()->catalog()->boms() | BomService | Bill of Materials (Bom & BomComponent) authoring, DFS circular dependency prevention, and multi-level material explosion |