Notifications

Status: v1 lite — adapter context
Packages: packages/domain/notifications, packages/application/notifications

Purpose

The Notifications context is responsible for delivering messages to members when domain events occur in other contexts. It is an adapter context: it does not own domain rules of its own, but acts as the delivery mechanism for events raised elsewhere (booking confirmations, compliance alerts, invoice issuances, etc.).

Notifications is intentionally kept thin and decoupled. Other contexts raise events; the Notifications context decides how to deliver them and to which channels.

Key concepts

Notification

A message to be delivered to one or more recipients.

Key attributes:

• id — unique identifier
• recipientId — the target member (MemberId)
• channel — email | sms | in-app
• subject — message subject (for email; may be omitted for SMS/in-app)
• body — message body
• triggerEvent — the event that caused this notification (e.g. booking.confirmed, compliance.alert.lapsed)
• status — pending | sent | failed
• sentAt — null until delivery confirmed
• failureReason — null unless status: failed

Channel

The delivery mechanism for a Notification. Supported channels in v1:

• Email — delivered via a transactional email provider (e.g. Postmark, Resend).
• SMS — delivered via a messaging provider (e.g. Twilio). Optional in v1.
• In-app — surfaced inside the Baseleg UI. Lowest priority, simplest to implement.

Delivery

The act and outcome of sending a Notification to a Channel. Delivery is attempted by infrastructure adapters and the result is recorded on the Notification entity.

Domain rules

1. A Member’s contact preferences determine which channels are used for a given event type.
2. If a delivery fails, it should be retried with backoff up to a configurable limit.
3. A failed Notification does not block the originating domain event — notifications are fire-and-forget from the perspective of other contexts.
4. In-app notifications are always created, even if email/SMS delivery fails.

Key use cases

• sendNotification — dispatch a Notification to the appropriate channels for a recipient.
• listNotifications — return recent notifications for a Member (used by the in-app inbox).
• markNotificationRead — acknowledge an in-app notification.
• retryFailedNotification — re-attempt delivery of a failed Notification.

Events that trigger notifications

Event source	Event	Default channels
Scheduling	booking.confirmed	Email, in-app
Scheduling	booking.cancelled	Email, in-app
Compliance	compliance.alert.approaching	Email, in-app
Compliance	compliance.alert.lapsed	Email, SMS, in-app
Billing	invoice.issued	Email

Cross-context relationships

Notifications is downstream of all other contexts. It receives events but does not publish to them.

Context	Usage
People	Reads Member contact details and channel preferences for delivery
All contexts	Receives domain events that trigger notification dispatch