Notification Architecture

Component Map

Data Model

• Single notification document per logical event.
• surfaces[] indicates delivery targets.
• statusBySurface.<surface> tracks lifecycle timestamps and metadata.

API Boundary

Read APIs (apps/api/src/modules/notification) are strict surface contracts. Write/producer APIs (apps/api/src/modules/notifications) map business events to targets and dispatch.

Realtime Boundary

• Room key: notifications:{userId}:{surface}
• Join/sync handlers in gateway
• Publish helpers in realtime service
• Event history replay on reconnect

---

Transactional Layer Architecture (NEW)

Architecture Overview

Layer Responsibilities

Event Flow Sequence

2. Context Build: OrderNotificationService queries order + customer data, builds EventContext
3. Event Resolution: Resolves event type (e.g., ORDER_PAYMENT_RECEIVED_CHECKOUT) based on order_source
4. Router Entry: Calls notificationRouter.routeEvent(event, context)
5. Config Lookup: Router gets EventConfig from catalog (templateId, channels, priority, title)
6. Dedupe Check: Router builds dedupe key, attempts Redis SET NX EX
   • If duplicate: return early (no send)
   • If Redis fail: allow send (fail-open)
7. Recipient Resolution: Router calls recipientResolver.resolve(context)
8. Channel Dispatch: For each channel:
   • Push: Build notification body, call sendToUser() with inAppTargets + pushTargets
   • Email: Render template, call sendEmailToUsers()
9. Queue Enqueue: Both methods add jobs to BullMQ NOTIFICATIONS queue
10. Processing: NotificationsProcessor handles delivery (MongoDB persist, Firebase push, realtime emit)

Deduplication Strategy

Two-layer deduplication:

1. Router Layer (Redis):

   • Key: notification_sent:transactional:<event>:<orderId>:<productId>
   • TTL: 7 days
   • Method: SET key value EX ttl NX
   • Purpose: Prevent rapid duplicate sends within 7-day window

2. Processor Layer (MongoDB):

   • Field: externalRef
   • Constraint: Unique partial index when externalRef is string
   • Purpose: Ensure idempotent persistence per recipient

Source-Aware Event Resolution

The OrderNotificationService resolves different events based on order_source field:

Channel Configuration

All transactional events are configured with:

• Push: inAppTargets=["mobile_in_app", "web_in_app"], pushTargets=["mobile_push"]
• Email: HTML template with order details, CTAs

Priority mapping:

• High: Payment events (received/failed), Refunds
• Normal: Order placed, Order cancelled

Fail-Open Reliability Model

Relationship to Base Infrastructure

The transactional layer does not replace the base infrastructure. Instead:

1. Reuses NotificationsService for queue enqueue
2. Reuses NotificationsProcessor for delivery
3. Reuses MongoDB schemas for persistence
4. Reuses Firebase for push delivery
5. Reuses RealtimeService for in-app events
6. Adds event standardization, deduplication, template rendering on top

Base infrastructure consumers outside transactional order flow continue using direct sendToUser() / sendEmailToUsers() calls without going through the transactional router.

Event Coverage

Shared Outbox Cleanup Architecture (NEW)

All transactional notification events that persist through outbox_events participate in a shared cleanup lifecycle.

Key behaviors:

• Pending rows are never deleted.
• Retention and DLQ threshold are environment-configured.
• Cleanup runs via BullMQ job execution, preserving retry/backoff semantics.