Notifications & comms

In-app notification center plus optional email/WhatsApp delivery, driven by a server-side event bus.

Overview

Aurea delivers notifications on two surfaces:

• In-app - a notifications table row per recipient, surfaced by the dashboard's bell (live unread badge + dropdown in both the client portal and the agency CRM). Always on.
• Out-of-app - email (Resend) and a WhatsApp stub, delivered by the API's CommsService and gated by each user's Settings notification preferences. Optional - enabled per provider by environment keys.

How an event becomes a notification

domain service (cases, tasks, documents, messages, advisor, leads)
        │  eventEmitter.emit('notify', payload)   <- one line, no cross-module import
        ▼
NotificationsListener (single consumer)
        ├── resolves recipients ({ userId } or { role: 'agency_member' })
        ├── writes the notifications row (source of truth)
        ├── publishes notificationAdded over graphql-ws (live badge)
        └── CommsService.deliver -> email / WhatsApp (preference-gated)

Domains never import the notifications module - they announce facts on the in-process event bus (@nestjs/event-emitter), and the listener decides what to do. A failed email or socket publish never loses the in-app notification.

Provider keys (all optional)

With a pair unset the matching adapter is a logged no-op - the API boots fine and in-app notifications keep working. Successful WhatsApp sends are metered as comms usage on the agency's plan.

Preferences

The Settings -> Notifications toggles (per category, email / inApp) govern out-of-app delivery. The gate lives in one place - CommsService.deliver - and reads the same user_preferences store the Settings page writes. Agency-operational events (task assigned, new lead) are not preference-gated.

See the GraphQL API reference for the Notification type, queries, mutations, and the notificationAdded subscription.