Domain Events & Integration Contracts

The Subcontracting domain communicates with the rest of the Obelaw ecosystem through a strict event-driven contract. It emits events when operational facts become immutable, and it consumes upstream signals from Procurement and PIM to initiate subcontracting activity.

---

1. Events Emitted by Subcontracting

Domain Event	Emitted When	Consumers
SubcontractOrderConfirmed	An SCO completes approval and becomes an operational commitment.	Inventory / WMS, Planning, Notifications
ComponentsDispatchedToSubcontractor	A Component Transfer Note is acknowledged by the subcontractor and the virtual location is updated.	Inventory / WMS, Subcontractor Portal, Reporting
SubcontractGoodsReceived	Finished goods are received and accepted into quarantine or sellable stock.	Quality, Inventory / WMS, Notifications
SubcontractProductionCompleted	A GRN is confirmed, backflushing is applied, and costs are capitalized.	Procurement, Accounting / FMS, Planning
SubcontractOrderClosed	An SCO is fully received, billed, and settled with no remaining open commitment.	Planning, Budgeting, Reporting
SubcontractVarianceRecorded	A yield, scrap, or quantity variance exceeds tolerance and is formally recorded.	Quality, Procurement, Accounting / FMS

Event Payload Characteristics

Emitted events contain only subcontracting-relevant facts:

• Document reference, version timestamp, and actor identity.
• Subcontractor organization and virtual location identifiers.
• Finished SKU, accepted quantity, unit of measure, and lot reference.
• Component lines with backflushed quantities and their source lot references.
• Service PO line references, tolling fee rates, and setup charges.
• Morph alias linking back to the originating SCO, BOM revision, and Procurement service PO.

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

---

2. Downstream Integration Contracts

Inventory / WMS Listens to SubcontractOrderConfirmed

When Subcontracting emits SubcontractOrderConfirmed, the Inventory / WMS context uses it to prepare outbound logistics and reserve component stock:

WMS Action	Purpose
Component Reservation	Reserve the planned component quantities in the source warehouse against the SCO.
Transfer Expectation	Create a pending transfer note expectation linked by SCO reference alias.
Subcontractor Location Staging	Ensure the subcontractor virtual location exists and is ready to receive inbound component stock.

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

Inventory / WMS Listens to ComponentsDispatchedToSubcontractor

When components arrive at the subcontractor, WMS updates the virtual location:

WMS Action	Purpose
Source Warehouse Decrement	Reduce available balance in the originating warehouse.
Virtual Location Increment	Increase on-book external asset balance at the subcontractor location.
Lot Traceability Update	Preserve lot references so backflushing can apply FIFO, FEFO, or specific-lot assignment policies.

Inventory / WMS Listens to SubcontractProductionCompleted

This event carries the backflushing instruction and the finished-goods receipt:

WMS Action	Purpose
Backflushing Application	Deduct consumed component quantities from the subcontractor virtual location per the BOM.
Finished Goods Receipt	Add accepted finished quantity to quarantine or sellable stock at the receiving location.
Lot / Serial Generation	Assign new lot or serial numbers to finished output for downstream traceability.

WMS applies the backflushing payload as an authoritative instruction from the Subcontracting domain. It does not independently recalculate consumption quantities.

---

Procurement Listens to SubcontractProductionCompleted

When Subcontracting emits SubcontractProductionCompleted, Procurement uses it to close the service commitment and process the vendor bill:

Procurement Action	Purpose
Service Receipt Recording	Record the quantity of services rendered against the service PO line.
Bill Matching Enablement	Make the accepted finished quantity available for matching against the subcontractor’s invoice.
Rate Variance Check	Compare invoiced tolling rate against the service PO rate within tolerance.
Close Service PO	Close the service PO when all SCO quantities are received, billed, and settled.

Accounting / FMS Listens to SubcontractProductionCompleted

When Subcontracting emits SubcontractProductionCompleted, the Accounting / FMS context capitalizes the finished inventory value:

FMS Action	Purpose
Material Cost Capitalization	Transfer the value of backflushed components from the subcontractor virtual asset account into the finished goods inventory account.
Service Cost Capitalization	Add the matched tolling fee and allocated setup charge to the finished goods inventory value.
Total Unit Cost Calculation	Compute the final capitalized unit cost as raw material cost plus processing fee.
Variance Posting	Post yield loss, scrap, or rate variances to the appropriate variance accounts.

The total capitalized unit cost is defined as:

$$ \text{Total Unit Cost} = \sum \text{Backflushed Component Unit Costs} + \text{Tolling Fee per Unit} + \text{Allocated Setup Charge per Unit} $$

FMS does not read SCO or BOM details from Subcontracting after the event; it relies on the matched payload delivered through the ACL.

---

3. Inbound Events Consumed by Subcontracting

Operational Event	Source Context	Subcontracting Action
ServicePurchaseOrderApproved	Procurement	Create or validate an SCO linked to the approved service PO and subcontractor.
BOMRevisionApproved	PIM / BOM	Refresh available BOM versions for SCO creation and lock the selected revision on confirmation.
ProductionDemandSignal	Planning / MRP	Propose subcontracting as a fulfillment option when internal capacity is insufficient.
QualityReleaseConfirmed	Quality / WMS	Move finished goods from quarantine to sellable inventory.
VendorBillMatched	Procurement	Confirm that service costs are approved for capitalization into finished inventory value.

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