Domain Events & Integration Contracts

The Purchases & Procurement domain communicates with the rest of the Obelaw ecosystem through a strict event-driven contract. It emits procurement events for downstream consumers and consumes demand signals to initiate sourcing activity.

---

1. Events Emitted by Purchases

Domain Event	Emitted When	Consumers
PurchaseOrderApproved	A purchase order completes approval and becomes a binding commitment.	Inventory / WMS, Planning, Notifications
VendorBillMatched	A vendor bill passes 3-way matching and is ready for payment authorization.	Accounting / FMS, Treasury
VendorBillRejected	A vendor bill fails 3-way matching or is rejected during discrepancy workflow.	Procurement, Supplier Portal, Accounting
PurchaseOrderClosed	A purchase order is fully received, billed, and settled with no remaining open commitment.	Planning, Budgeting, Reporting
SupplierPerformanceRecorded	Fulfillment metrics such as on-time delivery or quality rejection are captured.	Supplier Scorecards, Reporting

Event Payload Characteristics

Emitted events contain only procurement-relevant facts:

• Document reference and version timestamp.
• Supplier organization and site identifiers.
• Line-level quantities, prices, currencies, and UOMs.
• Morph alias linking back to originating PR, PO, or RTV document.
• Actor identity who triggered the transition.

They do not expose internal details from Inventory, Accounting, or Customer contexts.

---

2. Downstream Integration Contracts

Inventory / WMS Listens to PurchaseOrderApproved

When Procurement emits PurchaseOrderApproved, the Inventory / WMS context uses it to prepare inbound logistics:

WMS Action	Purpose
Advance Shipping Notice (ASN) staging	Reserve receiving dock capacity based on expected delivery date and quantity.
Inbound Receiving expectation	Create a pending receiving record linked by PO reference alias.
Quality Inspection queue	Flag items requiring inspection or certificate verification upon arrival.

The WMS does not query Procurement tables directly; it consumes the event payload and stores only its own polymorphic reference back to the PO.

Accounting / FMS Listens to VendorBillMatched

When Procurement emits VendorBillMatched, the Accounting / FMS context posts the corresponding accounts payable journal entry:

FMS Action	Purpose
AP liability recognition	Debit expense or asset account, credit accounts payable.
Landed cost allocation	Distribute freight, duty, and handling costs across received lines.
Variance recording	Post quantity and price variance accounts when tolerances are exceeded but approved.

The FMS does not read vendor bill details from Procurement after the event; it relies on the matched payload delivered through the ACL.

---

3. Inbound Events Consumed by Purchases

Operational Event	Source Context	Procurement Action
StockReplenishmentSignal	Inventory / Planning	Generate a purchase requisition for items below reorder point.
ProductionMaterialDemand	Manufacturing / MRP	Generate a purchase requisition for raw material requirements.
GoodsReceivedNoteConfirmed	Inventory / WMS	Update PO receipt status and make quantities available for bill matching.
QualityRejectionRecorded	Inventory / WMS	Trigger debit note issuance and return-to-vendor workflow.

These events are translated through the ACL into internal procurement commands without direct database coupling to operational contexts.