Eventing & Integration
The platform is event-driven: Medusa and the NestJS domains stay coherent by exchanging domain events, not by sharing tables. This is the seam that makes the polyglot split safe.
The event bridge
- Outbox pattern: the producer writes the business change and the event row in the same transaction, so an event is never lost if the write commits. A relay ships outbox rows to BullMQ.
- BullMQ on Redis is the transport (queues, retries, delays, DLQ).
- Idempotent consumers: every handler dedupes on
eventIdand is safe to retry. - Dead-letter queue: poison messages park in a DLQ with alerting.
Canonical event catalog (initial)
| Event | Emitted by | Consumed by | Effect |
|---|---|---|---|
customer.created | Medusa | CRM | create/refresh 360 profile |
order.placed | Medusa | Loyalty, CRM, Automation | accrue points (pending), lead/automation triggers |
order.delivered | Medusa | Warranty, FSM | mark warranty-eligible; offer installation |
serial.assigned | Medusa/Inventory | Warranty | register serial → asset (unregistered) |
warranty.registered | Warranty | CRM, Notifications, Loyalty | confirm; bonus points |
installation.completed | FSM | Notifications (delayed 7d), Loyalty, Warranty | schedule testimonial request; activate warranty start |
ticket.created | FSM | Notifications, Automation | acknowledge customer; webhook out |
ticket.closed | FSM | CRM, Notifications, BI | CSAT request; metrics |
amc.due_soon | FSM (scheduler) | Notifications | renewal reminder |
claim.approved | Warranty | FSM, Finance | create repair/replace job; cost recovery |
payment.captured | Medusa/Hyperswitch | Finance, Loyalty | reconcile; confirm points |
dealer.target.updated | DMS | Notifications, BI | notify dealer; refresh dashboards |
Events are versioned (
v1,v2) and documented in API Surface. Payloads carry IDs + a minimal snapshot; consumers fetch more via the BFF if needed.
The 7-day testimonial flow (worked example)
A delayed BullMQ job (not a cron scan) is scheduled when installation completes; on fire it re-checks validity (e.g. no open complaint) before asking. See Marketing & Content module.
Inbound integrations
| Source | Mechanism | Lands as |
|---|---|---|
| Hyperswitch | webhook → BFF | payment.* events |
| Shiprocket | webhook → BFF | shipment.* → updates Medusa fulfillment |
| Amazon/Flipkart | scheduled pull + webhook | channel order/inventory sync (see Marketplaces) |
Outbound automation — n8n, Zapier & Pabbly
The platform exposes selected domain events to automation engines so the business can wire workflows (e.g. "complaint → auto-assign technician via n8n", "new high-value order → Slack", "AMC due → WhatsApp via Pabbly"). n8n (self-hosted, in-cluster) is the primary internal engine; Zapier/Pabbly cover SaaS no-code.
- An Automation dispatcher subscribes to whitelisted events and POSTs signed webhooks (HMAC with
N8N_WEBHOOK_SECRET/ZAPIER_WEBHOOK_SECRET/PABBLY_WEBHOOK_SECRET) to configured endpoints. - Subscriptions (event → engine + URL) are tenant config, managed in admin.
- Full contract, payloads, retries, and the n8n recipe catalog: Automation: n8n, Zapier & Pabbly.
Reliability rules
- Outbox on every producer; never emit from application memory only.
- Idempotent consumers, keyed on
eventId. - Retries with backoff, then DLQ + alert.
- Versioned event schemas; additive changes preferred.
- Webhooks (in and out) are signed and verified.
Operating this in production — delivery guarantees, crash behaviour per component, scaling knobs, Redis HA, DLQ replay, and the env reference: see the Eventing Reliability & Operations Runbook.