Skip to content

notifications

Purpose

notifications is the platform's fan-out notification service. It subscribes to the *.events Redis Pub/Sub pattern, matches incoming events against configured NotificationSubscription rules, creates Notification rows, and delivers them via AWS SES (email) or Slack. It supports per-user opt-out preferences, suppression lists, and per-template PHI-at-rest encryption.

Key endpoints

POST /v1/notifications — create a notification manually GET /v1/notifications/:id — fetch a notification record GET /v1/notifications — list notifications GET /v1/notifications/preferences/:userId — fetch notification preferences for a user PUT /v1/notifications/preferences/:userId — set notification preferences for a user GET /v1/notifications/admin/subscriptions — list event-to-notification subscriptions POST /v1/notifications/admin/subscriptions — create a subscription (maps an event type to a template) PATCH /v1/notifications/admin/subscriptions/:id — update a subscription DELETE /v1/notifications/admin/subscriptions/:id — remove a subscription GET /v1/notifications/admin/templates — list notification templates GET /v1/notifications/admin/templates/:code — fetch a template by code PUT /v1/notifications/admin/templates/:code — create or update a template POST /v1/notifications/admin/templates/:code/render-preview — render a preview of a template GET /v1/notifications/admin/suppressions — list suppression list entries POST /v1/notifications/admin/suppressions — add an address to the suppression list DELETE /v1/notifications/admin/suppressions/:id — remove a suppression entry POST /v1/notifications/admin/queue/re-enqueue-stuck — re-enqueue notifications stuck in queued status

Database tables

Template — notification templates with channel (email / slack), body, PHI flag, and category NotificationSubscription — rules mapping event types to templates and recipient resolution logic Notification — notification records (status, channel, recipient, encrypted variables) NotificationPreference — per-user opt-out preferences per channel DeliveryAttempt — delivery attempt log (success / failure, provider response) EventInbox — idempotency inbox that de-duplicates inbound events SuppressionList — address-level suppression (email addresses or Slack IDs)

Events

*.events (pattern) — consume — subscribes to all <domain>.events Redis Pub/Sub channels; fans out to matching subscriptions notification.sent — emit — published on the notification.events channel after successful delivery notification.failed — emit — published on the notification.events channel after delivery failure notification.suppressed — emit — published on the notification.events channel when delivery is suppressed

Dependencies

  • AWS SES — email delivery (SES_REGION, SES_FROM_ADDRESS env vars)
  • Slack — Slack delivery via bot token (SLACK_BOT_TOKEN env var)
  • BullMQ — delivery job queue
  • Redis — event subscription (Redis Pub/Sub) and BullMQ backing store
  • MySQL — primary store, accessed via Prisma 7 driver-adapter pattern
  • auth — JWT verification via @sa-platform/auth-client

Where to learn more