Domain Events & Integration Contracts
POS communicates with the rest of the Obelaw ecosystem exclusively through domain events and integration contracts. This event-driven architecture preserves domain boundaries, enables asynchronous downstream processing, and allows central systems to react to frontline retail facts without blocking checkout speed.
1. Domain Events Emitted
The following table lists the primary domain events emitted by the POS bounded context.
| Event Name | Emitted When | Payload Highlights |
|---|
| PosSessionOpened | Cashier opens a shift session with declared opening float. | Session ID, terminal ID, store, cashier, opening float, timestamp. |
| PosSaleCompleted | A customer sale is finalized and receipt issued. | Receipt number, terminal sequence, store, line items, taxes, tenders, total, customer alias. |
| PosSaleRefunded | A return/refund transaction is completed. | Original receipt reference, return receipt number, returned items, refund tenders, reason. |
| PosCashDropRecorded | Cash is removed from drawer to safe during shift. | Session ID, amount, timestamp, reason, supervisor, drop slip reference. |
| PosPettyExpenseRecorded | Cash is disbursed for operational expense. | Session ID, amount, timestamp, reason, approver. |
| PosReceiptCancelled | An entire transaction is abandoned before payment. | Receipt draft ID, terminal, timestamp, reason. |
| PosLineItemVoided | A line item is removed before transaction completion. | Receipt ID, line item, reason, operator. |
| PosPaymentAuthorized | Card or digital wallet payment is authorized. | Receipt ID, tender type, authorization code, amount, terminal. |
| PosSessionClosed | Shift session is closed with reconciliation totals. | Session ID, sales totals, refund totals, tender totals, tax totals, discrepancy, closing float. |
| PosDrawerDiscrepancyRecorded | Closing count differs from expected cash. | Session ID, expected cash, actual cash, overage/shortage amount, reason. |
| PosOfflineReplayCompleted | Queued offline transactions are successfully synchronized. | Terminal ID, sequence range, transaction count, conflict summary. |
| PosCustomerLinked | A customer profile is attached to a transaction. | Receipt ID, customer alias, loyalty account. |
2. Integration Contracts & Asynchronous Reactions
Downstream contexts subscribe to POS events and translate them into their own internal workflows. The POS context does not know how these reactions are implemented; it only publishes facts.
Inventory / WMS Reactions
| Subscribed Event | WMS Action | Resulting WMS Document |
|---|
| PosSaleCompleted | Deduct sold quantities from the store’s floor stock bucket. | Stock Deduction / Goods Issue Note. |
| PosSaleRefunded | Add returned quantities back to the store’s floor stock or designated returns location. | Stock Addition / Goods Received Note. |
| PosOfflineReplayCompleted | Reconcile any optimistic local stock decrements with central stock levels. | Inventory Reconciliation Adjustment. |
Responsibility Boundary
- POS reports what was sold or returned, with product codes and quantities.
- WMS decides from which floor stock bucket, lot, or location to deduct or receive stock.
- POS never instructs WMS on bin-level decisions; WMS never slows down checkout.
Accounting / FMS Reactions
| Subscribed Event | FMS Action | Resulting FMS Impact |
|---|
| PosSessionClosed | Post aggregated sales revenue by tender type and tax category. | Revenue Journal Vouchers. |
| PosSessionClosed | Post cash-on-hand movement reflecting net cash collected. | Cash / Bank Deposit Journal. |
| PosSessionClosed | Post tax liabilities collected during the session. | Tax Payable Journal Entries. |
| PosDrawerDiscrepancyRecorded | Post overage or shortage as a variance expense or income. | Cash Variance Journal Voucher. |
| PosSaleCompleted | Update revenue recognition sub-ledger if accounting method requires per-receipt posting. | Revenue Sub-ledger Entry. |
| PosSaleRefunded | Post refund contra-revenue and tax liability reversal. | Refund Journal Vouchers. |
Responsibility Boundary
- POS emits session-level and receipt-level sales facts.
- FMS applies chart of accounts, tax codes, revenue recognition policies, and variance rules.
- POS does not post journal entries; FMS does not issue receipts.
Sales / OMS Reactions
| Subscribed Event | OMS Action | Resulting OMS Document |
|---|
| PosSaleCompleted | Record sale in enterprise order history for reporting and customer service. | Order History Record. |
| PosSaleRefunded | Link refund to original sale and update order status. | Return Record. |
| PosCustomerLinked | Attach transaction to customer order history. | Customer Order History Update. |
Responsibility Boundary
- POS executes the frontline transaction.
- OMS maintains enterprise order history, fulfillment exceptions, and customer service context.
CRM / Loyalty Reactions
| Subscribed Event | CRM / Loyalty Action | Resulting Output |
|---|
| PosSaleCompleted | Accrue loyalty points based on sale value and customer tier. | Loyalty Points Accrual. |
| PosSaleRefunded | Reverse or adjust loyalty points previously accrued. | Loyalty Points Reversal. |
| PosCustomerLinked | Link transaction to customer profile and touchpoint history. | Customer Activity Record. |
| PosSaleCompleted | Trigger post-purchase engagement (feedback, warranty, cross-sell). | Campaign Trigger. |
Responsibility Boundary
- POS identifies the customer where possible and emits sale facts.
- CRM / Loyalty manages points, profiles, and engagement asynchronously without blocking checkout.
PIM / Catalog Reactions
| Subscribed Event | PIM Action | Resulting Output |
|---|
| PosSaleCompleted (aggregated) | Update product velocity and sales analytics. | Sales Velocity Report. |
| PosOfflineReplayCompleted | Refresh product cache availability indicators on terminals. | Cache Update. |
Responsibility Boundary
- PIM owns product master data and analytics.
- POS consumes product snapshots and contributes sales velocity facts.
Payments / Card Acquirer Reactions
| Subscribed Event | Acquirer Action | Resulting Output |
|---|
| PosPaymentAuthorized | Capture authorized funds for settlement. | Settlement Batch. |
| PosSaleRefunded | Process refund to original card or wallet. | Refund Settlement. |
Responsibility Boundary
- POS initiates authorization and captures payment events.
- Acquirer owns fund settlement, chargebacks, and reconciliation.
3. Event Flow Architecture
POS events flow from edge terminals through an ACL to central event consumers:
┌─────────────────────┐ ┌─────────────────────────────┐ ┌─────────────────────┐
│ POS Terminal │ │ Anti-Corruption Layer │ │ Central Domain │
│ (Edge Publisher) │ ───► │ (Validate / Translate / │ ───► │ (Event Subscriber) │
│ │ │ Sequence / Replay) │ │ │
└─────────────────────┘ └─────────────────────────────┘ └─────────────────────┘
ACL Responsibilities
| Responsibility | Description |
|---|
| Sequence Validation | Ensures terminal sequences are monotonic and gap-free. |
| Duplicate Detection | Rejects or idempotently accepts duplicate transaction events. |
| Payload Translation | Converts terminal-specific receipt formats into canonical event payloads. |
| Store Mapping | Maps terminal IDs to store, tax jurisdiction, and business calendar. |
| Downstream Routing | Routes events to WMS, FMS, OMS, CRM, and PIM subscribers. |
4. Offline Replay Contracts
When a terminal reconnects, queued transactions are replayed under strict contracts:
| Contract Rule | Description |
|---|
| Sequential Replay | Transactions are replayed in monotonic sequence order. |
| Idempotency | Central systems accept duplicate events with the same sequence and payload without double processing. |
| Conflict Detection | Conflicting events (e.g., gift card spent elsewhere) are flagged for manual resolution. |
| Partial Replay | If replay fails mid-batch, the terminal retries from the first unaccepted sequence. |
| Acknowledgment | Central systems acknowledge the highest contiguous accepted sequence. |
Conflict Resolution Examples
| Conflict Scenario | Resolution |
|---|
| Gift card balance exhausted during offline period | Refund or alternative tender requested from customer; shortfall logged as variance. |
| Product price changed while offline | Original snapshot price honored; variance between old and new price logged for review. |
| Product discontinued while offline | Sale honored if local cache was valid; inventory disposition handled by WMS. |
| Duplicate sequence with different payload | Manual investigation; terminal state reconciliation required. |
5. Event Sourcing & Replay Considerations
Because POS state is reconstructed from immutable event history, downstream contexts can replay events for recovery, audit, or reprocessing:
| Replay Scenario | Rule |
|---|
| WMS replay | Re-apply stock deductions using receipt sequence as idempotency key. |
| FMS replay | Re-post session aggregates using session ID and sequence range as idempotency keys. |
| CRM replay | Re-accrue loyalty points only if not already processed for the receipt. |
All events carry a unique event identifier, terminal sequence, store reference, session reference, timestamp, and correlation identifier to support idempotent processing and end-to-end traceability.
6. Anti-Corruption Layer Translation Examples
| POS Event | ACL Translation for WMS | ACL Translation for FMS |
|---|
PosSaleCompleted | Convert product codes to WMS SKU strings; map store to floor stock location. | Aggregate session sales into revenue, tax, and cash journal lines by tender type. |
PosSaleRefunded | Map returned items to store returns location; restore stock. | Post contra-revenue and tax reversal entries. |
PosSessionClosed | Confirm no pending stock adjustments from offline replay. | Post final cash deposit, revenue, tax, and variance journal vouchers. |
This event-driven, ACL-protected integration model ensures that POS remains an autonomous, high-performance edge domain while participating fully in the broader ERP ecosystem.