Catalog - Domain Events & Integration Contracts
Comprehensive catalog of emitted domain events, downstream integration contracts, and asynchronous event choreography for the Catalog domain (obelaw/ium-catalog).
In Domain-Driven Design, Domain Events represent significant business facts that have occurred within the domain. As emphasized in Vlad Khononov’s Learning Domain-Driven Design, domain events are immutable historical records. Once dispatched, they cannot be altered or retracted.
The Catalog bounded context (obelaw/ium-catalog) communicates with downstream operational engines primarily through asynchronous domain events. When a product is created, a variant updated, or an engineering BOM revision approved, Catalog broadcasts an event over the enterprise event bus. Downstream bounded contexts—such as Warehousing, Sales, Point of Sale, and Manufacturing—subscribe to these events and materialize local projections according to their own business rules, eliminating tight database-level coupling.
1. Domain Event Delivery Guarantees
To ensure bulletproof reliability across distributed enterprise architectures, Catalog implements the Transactional Outbox Pattern:
sequenceDiagram
participant Aggregate as Product Aggregate
participant Outbox as Transactional Outbox
participant Relay as Event Relay Worker
participant Bus as Enterprise Message Bus
participant Downstream as Downstream Subscribers
rect rgb(245, 245, 255)
Note over Aggregate,Outbox: Atomic Database Transaction
Aggregate->>Aggregate: Apply State Mutation & Enforce Invariants
Aggregate->>Outbox: Persist Domain Event in Outbox Table
end
Relay->>Outbox: Poll Uncommitted Events
Relay->>Bus: Dispatch Event (At-Least-Once Delivery)
Bus->>Downstream: Distribute to Subscribed Handlers
Downstream->>Downstream: Idempotent Event Processing (Deduplicate via Event ID)
Relay->>Outbox: Mark Event as Dispatched
Core Event Architectural Standards
- At-Least-Once Delivery: Events are guaranteed to be published to the message broker. Subscribers must implement idempotent message handling using unique
event_idkeys. - Envelope Metadata: Every emitted event payload encapsulates standardized envelope headers:
event_id: Unique UUIDv4 identifier for deduplication.correlation_id: Distributed tracing identifier linking chained cross-domain activities.causation_id: The identifier of the command or antecedent event that caused this event.occurred_at: Microsecond-precision UTC timestamp.schema_version: Explicit version number supporting backward-compatible evolution.
2. Catalog of Emitted Domain Events
The table below catalogs the authoritative domain events emitted by the Catalog bounded context:
| Event Name | Business Trigger | Conceptual Payload Key Attributes | Downstream Enterprise Subscribers |
|---|---|---|---|
| ProductCreated | Initial product shell (SPU) instantiated. | product_id, sku, name, status, actor_id. | Audit Service, Catalog Indexer. |
| ProductStatusChanged | Lifecycle state transition executed. | product_id, previous_status, new_status, actor_id, reason. | Workflow Engine, Audit Service. |
| ProductPublished | 100% completeness passed; item goes live. | product_id, target_channel, completeness_report, actor_id. | Sales / OMS, Storefronts, POS, WMS, Accounting. |
| ProductDeprecated | Discontinuation declared; sell-down active. | product_id, superseding_sku, actor_id. | Sales / OMS, Purchasing, Storefronts. |
| ProductArchived | Terminal retirement committed. | product_id, actor_id. | ERP Core, Data Warehouse, Master Catalog. |
| VariantCreated | Concrete physical SKU generated. | variant_id, sku, product_id, actor_id. | Inventory / WMS, Sales / OMS, Accounting. |
| VariantBarcodeAssigned | Validated GS1 barcode linked to variant. | entity_id, barcode, previous_barcode, actor_id. | Point of Sale (POS), Inventory / WMS. |
| BOMCreated | New engineering recipe revision created. | bom_id, product_id, code, version, actor_id. | Engineering QA, Cost Accounting. |
| BOMRevisionApproved | Engineering sign-off on assembly recipe. | bom_id, product_id, code, actor_id. | Manufacturing / MRP, Subcontracting. |
3. Downstream Integration Contracts & Reactions
Downstream bounded contexts subscribe to Catalog domain events to drive local operational workflows while maintaining domain isolation:
flowchart LR
Catalog["Catalog Domain Events (ium-catalog)"] --> Bus["Enterprise Event Bus"]
Bus -->|"VariantCreated / BarcodeAssigned"| WMS["Inventory / WMS<br/>Master Item Setup"]
Bus -->|ProductPublished| OMS["Sales / OMS<br/>Sellable Catalog Snapshot"]
Bus -->|VariantBarcodeAssigned| POS["Point of Sale (POS)<br/>Scanner Memory Cache"]
Bus -->|BOMRevisionApproved| MRP["Manufacturing / MRP<br/>Work Order Routing"]
Bus -->|ProductPublished| Web["Storefronts & CDN<br/>Edge Cache & Search Index"]
Inventory / Warehouse Management (WMS) Integration
| Subscribed Event | Downstream Action Executed in WMS | Materialized Enterprise Result |
|---|---|---|
| VariantCreated | Instantiates a new Warehouse Master Item profile with dimensions, weight, and handling flags. | New warehouse SKU profile created. |
| VariantBarcodeAssigned | Registers optical barcode in warehouse scanner gun lookup tables. | Receiving and picking scanner index updated. |
| ProductArchived | Validates physical stock balance is exactly zero; decommissions SKU permanently. | Warehouse item record sealed read-only. |
Boundary Demarcation
- Catalog owns: Packaged dimensions, gross weight mass, storage UOM, and optical barcodes.
- WMS owns: Shelf bin coordinates, picking paths, cycle count audits, and real-time physical quantity balances.
Sales / Order Management (OMS) Integration
| Subscribed Event | Downstream Action Executed in OMS | Materialized Enterprise Result |
|---|---|---|
| ProductPublished | Adds product and active variant SKUs to the sellable catalog search index. | Live sales catalog snapshot refreshed. |
| ProductDeprecated | Disables backorders; limits order line quantities to on-hand inventory availability. | Sell-down flag applied; backorders blocked. |
| ProductArchived | Delists SKU completely from sales quotation engines and repeat order templates. | Order line creation prohibited. |
Boundary Demarcation
- Catalog owns: Master merchandise specifications, variant definitions, and baseline catalog MSRP.
- OMS owns: Customer tier discounts, promo code engines, contractual order promises, and fulfillment dispatch.
Point of Sale (POS) Frontline Integration
| Subscribed Event | Downstream Action Executed in POS | Materialized Enterprise Result |
|---|---|---|
| ProductPublished | Syncs item title, SKU, and tax category to local register offline database. | Local checkout register database refreshed. |
| VariantBarcodeAssigned | Ingests barcode-to-SKU mapping into the in-memory fast scanner table. | Ultra-low-latency laser scanner index updated. |
| ProductStatusChanged | If suspended, immediately flags barcode as suspended; blocks scan at cash register checkout. | Barcode scan locked at POS register. |
Boundary Demarcation
- Catalog owns: Canonical barcodes, merchandise descriptions, and default tax classification codes.
- POS owns: Cash drawer sessions, cashier authentication, receipt printing, and split tender processing.
Manufacturing (MRP) & Subcontracting Integration
| Subscribed Event | Downstream Action Executed in MRP | Materialized Enterprise Result |
|---|---|---|
| BOMRevisionApproved | Binds approved recipe revision to work order generation routes and bill-of-materials explosion. | Active production formulation locked. |
| BOMRevisionApproved | In Subcontracting, updates purchase order component dispatch ratios for external assembly partners. | Subcontractor material dispatch ratio updated. |
| ProductDeprecated | Cancels future scheduled production runs; halts raw material replenishment triggers. | Manufacturing schedule purged of retired SKU. |
Boundary Demarcation
- Catalog owns: Multi-level BOM component trees, consumption quantities, scrap allowances, and engineering revision tags.
- MRP owns: Factory work center routing, machine schedules, worker labor shifts, and physical material staging.
E-Commerce Storefronts & Digital Channels
| Subscribed Event | Downstream Action Executed in Digital Channels | Materialized Enterprise Result |
|---|---|---|
| ProductPublished | Transforms channel-scoped DTO and indexes document in search engines (e.g., Elasticsearch, Meilisearch). | Public storefront search index updated. |
| ProductPublished | Dispatches instant edge cache purge requests to CDN providers for Product Detail Pages (PDP). | Fresh page rendered for digital shoppers. |
| ProductDeprecated | Injects HTTP 301 / 308 permanent redirect headers pointing to the designated superseding_sku. | Search engine SEO equity preserved. |
4. Concrete Event Classes in obelaw/ium-catalog (Obelaw\Ium\Catalog\Events\*)
In Laravel applications consuming obelaw/ium-catalog, register event listeners against these concrete event classes:
| Event Class | Dispatched By | Public Properties |
|---|---|---|
Obelaw\Ium\Catalog\Events\ProductCreated | ProductRepository::create() | Product $product, ?string $actorId |
Obelaw\Ium\Catalog\Events\VariantCreated | ProductRepository::create(), VariantMatrixService::generateMatrix() | ProductVariant $variant, Product $product, ?string $actorId |
Obelaw\Ium\Catalog\Events\VariantBarcodeAssigned | ProductRepository::assignBarcode() | Model $entity, string $barcode, ?string $previousBarcode, ?string $actorId |
Obelaw\Ium\Catalog\Events\ProductStatusChanged | ProductLifecycleService::transitionTo() | Product $product, ProductStatus $previousStatus, ProductStatus $newStatus, ?string $actorId, ?string $reason |
Obelaw\Ium\Catalog\Events\ProductPublished | ProductLifecycleService::publish() | Product $product, string $channel, CompletenessReport $completenessReport, ?string $actorId |
Obelaw\Ium\Catalog\Events\ProductDeprecated | ProductLifecycleService::deprecate() | Product $product, ?string $supersedingSku, ?string $actorId |
Obelaw\Ium\Catalog\Events\ProductArchived | ProductLifecycleService::archive() | Product $product, ?string $actorId |
Obelaw\Ium\Catalog\Events\BOMCreated | BomService::create() | Bom $bom, ?string $actorId |
Obelaw\Ium\Catalog\Events\BOMRevisionApproved | BomService::approve() | Bom $bom, ?string $actorId |