Catalog

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_id keys.
  • 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 NameBusiness TriggerConceptual Payload Key AttributesDownstream Enterprise Subscribers
ProductCreatedInitial product shell (SPU) instantiated.product_id, sku, name, status, actor_id.Audit Service, Catalog Indexer.
ProductStatusChangedLifecycle state transition executed.product_id, previous_status, new_status, actor_id, reason.Workflow Engine, Audit Service.
ProductPublished100% completeness passed; item goes live.product_id, target_channel, completeness_report, actor_id.Sales / OMS, Storefronts, POS, WMS, Accounting.
ProductDeprecatedDiscontinuation declared; sell-down active.product_id, superseding_sku, actor_id.Sales / OMS, Purchasing, Storefronts.
ProductArchivedTerminal retirement committed.product_id, actor_id.ERP Core, Data Warehouse, Master Catalog.
VariantCreatedConcrete physical SKU generated.variant_id, sku, product_id, actor_id.Inventory / WMS, Sales / OMS, Accounting.
VariantBarcodeAssignedValidated GS1 barcode linked to variant.entity_id, barcode, previous_barcode, actor_id.Point of Sale (POS), Inventory / WMS.
BOMCreatedNew engineering recipe revision created.bom_id, product_id, code, version, actor_id.Engineering QA, Cost Accounting.
BOMRevisionApprovedEngineering 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 EventDownstream Action Executed in WMSMaterialized Enterprise Result
VariantCreatedInstantiates a new Warehouse Master Item profile with dimensions, weight, and handling flags.New warehouse SKU profile created.
VariantBarcodeAssignedRegisters optical barcode in warehouse scanner gun lookup tables.Receiving and picking scanner index updated.
ProductArchivedValidates 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 EventDownstream Action Executed in OMSMaterialized Enterprise Result
ProductPublishedAdds product and active variant SKUs to the sellable catalog search index.Live sales catalog snapshot refreshed.
ProductDeprecatedDisables backorders; limits order line quantities to on-hand inventory availability.Sell-down flag applied; backorders blocked.
ProductArchivedDelists 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 EventDownstream Action Executed in POSMaterialized Enterprise Result
ProductPublishedSyncs item title, SKU, and tax category to local register offline database.Local checkout register database refreshed.
VariantBarcodeAssignedIngests barcode-to-SKU mapping into the in-memory fast scanner table.Ultra-low-latency laser scanner index updated.
ProductStatusChangedIf 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 EventDownstream Action Executed in MRPMaterialized Enterprise Result
BOMRevisionApprovedBinds approved recipe revision to work order generation routes and bill-of-materials explosion.Active production formulation locked.
BOMRevisionApprovedIn Subcontracting, updates purchase order component dispatch ratios for external assembly partners.Subcontractor material dispatch ratio updated.
ProductDeprecatedCancels 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 EventDownstream Action Executed in Digital ChannelsMaterialized Enterprise Result
ProductPublishedTransforms channel-scoped DTO and indexes document in search engines (e.g., Elasticsearch, Meilisearch).Public storefront search index updated.
ProductPublishedDispatches instant edge cache purge requests to CDN providers for Product Detail Pages (PDP).Fresh page rendered for digital shoppers.
ProductDeprecatedInjects 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 ClassDispatched ByPublic Properties
Obelaw\Ium\Catalog\Events\ProductCreatedProductRepository::create()Product $product, ?string $actorId
Obelaw\Ium\Catalog\Events\VariantCreatedProductRepository::create(), VariantMatrixService::generateMatrix()ProductVariant $variant, Product $product, ?string $actorId
Obelaw\Ium\Catalog\Events\VariantBarcodeAssignedProductRepository::assignBarcode()Model $entity, string $barcode, ?string $previousBarcode, ?string $actorId
Obelaw\Ium\Catalog\Events\ProductStatusChangedProductLifecycleService::transitionTo()Product $product, ProductStatus $previousStatus, ProductStatus $newStatus, ?string $actorId, ?string $reason
Obelaw\Ium\Catalog\Events\ProductPublishedProductLifecycleService::publish()Product $product, string $channel, CompletenessReport $completenessReport, ?string $actorId
Obelaw\Ium\Catalog\Events\ProductDeprecatedProductLifecycleService::deprecate()Product $product, ?string $supersedingSku, ?string $actorId
Obelaw\Ium\Catalog\Events\ProductArchivedProductLifecycleService::archive()Product $product, ?string $actorId
Obelaw\Ium\Catalog\Events\BOMCreatedBomService::create()Bom $bom, ?string $actorId
Obelaw\Ium\Catalog\Events\BOMRevisionApprovedBomService::approve()Bom $bom, ?string $actorId

Our Premium Sponsors

Obelaw is proudly open-source. Continued development, bug fixes, and community support are made possible by the generosity of our sponsors.

Sponsor Obelaw