Domain Events & Integration Contracts

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 PIM bounded context communicates with downstream operational engines primarily through asynchronous domain events. When a product is created, a variant updated, or an engineering BOM revision approved, PIM 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, PIM 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 PIM bounded context:

Event Name	Business Trigger	Conceptual Payload Key Attributes	Downstream Enterprise Subscribers
ProductCreated	Initial product shell (SPU) instantiated.	product_id, handle, family_code, brand_id, master_category_code, status.	Audit Service, Catalog Indexer.
ProductEnriched	Marketing copy or localized attributes updated.	product_id, channel_scope, locale, changed_attributes_map.	Storefronts, Cache Purge Worker.
ProductFamilyAssigned	Attribute Family schema bound to product.	product_id, family_code, applied_attribute_groups.	Merchandising UI, Validation Engine.
ProductStatusChanged	Lifecycle state transition executed.	product_id, previous_state, new_state, actor_id, reason_code.	Workflow Engine, Audit Service.
ProductPublished	100% completeness passed; item goes live.	product_id, target_channel, effective_date, active_variant_skus, completeness_score.	Sales / OMS, Storefronts, POS, WMS, Accounting.
ProductSuspended	Emergency commercial quarantine initiated.	product_id, suspension_reason, actor_id, timestamp.	Storefront CDN, POS Registers, Marketplaces.
ProductDeprecated	Discontinuation declared; sell-down active.	product_id, sunset_date, superseding_sku, allow_backorders: false.	Sales / OMS, Purchasing, Storefronts.
ProductArchived	Terminal retirement committed.	product_id, archival_timestamp, zero_stock_verification_checksum.	ERP Core, Data Warehouse, Master Catalog.
VariantCreated	Concrete physical SKU generated.	variant_id, sku_code, product_id, option_values_map, dimensions, weight, base_uom.	Inventory / WMS, Sales / OMS, Accounting.
VariantUpdated	Physical dimensions, weight, or prices updated.	variant_id, sku_code, updated_dimensions, updated_weight, variant_price_override.	Inventory / WMS, Freight TMS, Sales / OMS.
VariantBarcodeAssigned	Validated GS1 barcode linked to variant.	variant_id, sku_code, barcode, symbology (EAN13, UPCA).	Point of Sale (POS), Inventory / WMS.
VariantDeactivated	Specific SKU removed from sale.	variant_id, sku_code, deactivation_reason.	Sales / OMS, Storefronts, POS.
AttributeFamilyCreated	Reusable attribute family template registered.	family_code, family_label, attribute_codes_list, validation_rules.	Schema Registry, Merchandising UI.
CategoryTreeUpdated	Hierarchy nodes restructured or moved.	tree_code, affected_node_ids, parent_node_mapping.	Storefront Navigation, Reporting Engine.
ProductCategorized	Product assigned to category leaf node.	product_id, tree_code, category_id, is_master_leaf.	Corporate Reporting, Search Indexes.
MediaAssetAttached	Visual asset or document linked with a role.	target_entity_type, target_id, asset_id, asset_role, file_url.	Digital Storefronts, POS Touchscreens, CDN.
MediaAssetRemoved	Media asset association severed.	target_entity_type, target_id, asset_id, asset_role.	CDN Purge Engine, Image Cache.
CompletenessEvaluated	Readiness calculation executed for channel.	product_id, channel_code, locale, score_percentage, missing_fields_list.	Merchandising QA Dashboard.
BOMRevisionApproved	Engineering sign-off on assembly recipe.	product_id, finished_sku, revision_tag, components_list (sku, gross_qty, scrap_rate).	Manufacturing / MRP, Subcontracting.

---

3. Downstream Integration Contracts & Reactions

Downstream bounded contexts subscribe to PIM domain events to drive local operational workflows while maintaining domain isolation:

flowchart LR
    PIM["PIM Domain Events"] --> Bus["Enterprise Event Bus"]

    Bus -->|"VariantCreated / Updated"| 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.
VariantUpdated	Updates volumetric package dimensions ($L \times W \times H$) and gross weight in bin-allocation algorithms.	Storage profile refreshed; bin capacity recalculated.
VariantBarcodeAssigned	Registers optical barcode in warehouse scanner gun lookup tables.	Receiving and picking scanner index updated.
VariantDeactivated	Marks warehouse SKU as non-replenishable; rejects new inbound receiving docks.	Inbound receiving dock blocked.
ProductArchived	Validates physical stock balance is exactly zero; decommission SKU permanently.	Warehouse item record sealed read-only.

Boundary Demarcation

• PIM 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.
VariantUpdated	Updates baseline MSRP prices in order line validation caches.	Order line pricing validator updated.
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

• PIM 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.
MediaAssetAttached	Downloads thumbnail asset tagged with swatch_icon or hero_image for cashier touchscreen buttons.	POS touchscreen button graphic updated.
ProductSuspended	Immediately flags barcode as suspended; blocks scan at cash register checkout.	Barcode scan locked at POS register.

Boundary Demarcation

• PIM 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

• PIM 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.
MediaAssetAttached	Triggers asynchronous image processing pipeline to generate responsive WebP and AVIF formats.	Responsive image CDN assets generated.
ProductDeprecated	Injects HTTP 301 / 308 permanent redirect headers pointing to the designated superseding_sku.	Search engine SEO equity preserved.