Outbound Signals to Humans and Systems
A notification is something the system sends out — an email to a customer, a WebSocket frame to a connected admin, a webhook to a partner's endpoint. @frenchexdev/ddd-notification reifies the outbound-signal boundary so the domain emits typed notification intents and the adapter handles the transport. The discipline the corpus enforces: notifications are emitted, never consumed back. They are not events. They are signals.
What Notification Reifies
The distinction between event and notification matters. An event names what happened in the past in the domain. A notification is the system's reaction to an event, projected outward. SubscriptionStarted is an event; the welcome email is the notification triggered by a subscriber on the event bus. The notification's failure does not invalidate the event — the customer subscribed regardless of whether the email arrived — but the notification's success is observable separately, and may itself trigger metrics or follow-up notifications.
The port reifies the send shape. Each notification class describes its payload — a WelcomeEmail carries the recipient, the subject template id, the personalisation fields; a SubscriptionExpiredWebSocket carries the connection id and the body — and the port's send(notification) dispatches to the appropriate adapter based on the notification's type. A typed dispatch table maps notification classes to adapter handlers; the application never reaches for SMTP libraries or WebSocket frames directly.
The Runtime: ddd-notification and adapters
Three packages — ddd-notification, ddd-notification-email-adapter, ddd-notification-websocket-adapter — all M4/M5 stubs pinned to NotificationExternalSignalRequirement. Email and WebSocket are the two first substrates; additional adapters (push notifications, SMS, webhook dispatcher) sit behind the same port.
The Analyzer: ddd-notification-analyzer
Spec-first (spec.ts). Priority Medium. Two rules — DDD-NOTIFICATION-001 recommends the Notifier suffix at info severity; DDD-NOTIFICATION-002 enforces single-per-file at error severity. The single-per-file rule matters because each notification has a distinct payload type and a distinct delivery substrate; consolidating them in one file conceals the substrate choices.
Cross-Links
- Typically dispatched by a subscriber on the
@EventBusreacting to a@DomainEvent. - Distinct from cross-context integration events: notifications go out, integration events stay within the system.
- Lives behind
@Port/@Adapter— the conformance suite covers retry, delivery confirmation, idempotence on duplicate sends. - Metrics on send-success/send-failure feed
@Metricsfor operational visibility.
Back to the series index.