Notifications

Event-driven notification dispatcher — consumes domain events from across the platform and delivers email and SMS messages to members.

Overview

The Notifications service is a pure consumer. It subscribes to Kafka topics from all other domains and translates each event into the appropriate member-facing communication: email, SMS, or both, depending on the member's channel preferences.

The service maintains a notification_log table that records every dispatch attempt and its outcome (sent, failed, retried). Member preferences are stored per party and control which channels are active and which event types they wish to receive. A retry job handles transient delivery failures by re-queuing unsent notifications up to a configurable maximum.

Channel integrations use SMTP for email and a pluggable SMS sender. The dispatcher fetches party contact details from Policy Admin before sending, so Notifications never needs its own copy of member PII beyond what's in the event payload.

Responsibilities

• Subscribe to domain events from Claims, Billing, Enrollment, Consent, and other services
• Translate events into templated email and SMS messages
• Respect per-member channel preferences (opt-in/opt-out per channel and event type)
• Track delivery status in the notification log
• Retry failed deliveries with exponential backoff
• Expose preference management endpoints for member portal and admin

Database

Schema: notifications

Table	Purpose
notification_preferences	Per-party channel and event-type preference flags
notification_log	Immutable log of every dispatch attempt with status and timestamps
projection_checkpoints	Kafka consumer offset tracking

API Routes

Method	Path	Auth	Description
GET	/preferences/{partyLocator}	JWT	Get notification preferences for a party
PUT	/preferences/{partyLocator}	JWT	Update notification preferences
GET	/preferences	JWT	Get preferences for the authenticated member
PUT	/preferences	JWT	Update preferences for the authenticated member
GET	/notifications/list	JWT	List notification log entries
GET	/notifications/{locator}	JWT	Get a notification log entry by locator
GET	/log/list	JWT	List notification log entries (web admin alias)
GET	/log/{locator}	JWT	Get log entry by locator (web admin alias)
POST	/send	Internal	Internal endpoint to dispatch a notification directly

Events

Publishes

The Notifications service does not publish any Kafka events.

Consumes

Topic	Action taken
claims.submitted	Sends member acknowledgement of claim receipt
claims.approved	Sends member approval notification
claims.rejected	Sends member rejection notice with reason
claims.paid	Sends member payment confirmation
billing.invoice.generated	Sends invoice ready / payment due reminder
billing.payment.received	Sends payment confirmation
billing.payment.missed	Sends payment missed / grace period warning
enrollment.policy.activated	Sends welcome / policy activated notification
enrollment.policy.lapsed	Sends coverage lapse warning
enrollment.policy.cancelled	Sends cancellation confirmation
consent.granted	Sends consent confirmation
consent.revoked	Sends consent revocation confirmation

Dependencies

Service	How used
Policy Admin	Fetches party contact details (email, phone) for outbound messaging

Key Design Decisions

Pure consumer pattern: Notifications has no write dependencies on other services. It only reads contact details from Policy Admin at send time. This means it can be deployed, scaled, or taken offline without impacting any other service's core functionality.

Preference-gated dispatch: Every dispatch attempt checks the member's current preferences before sending. This ensures opt-outs are respected even if the preference was updated after the triggering event was published.