Notifications
Multi-channel notification system delivering messages via email, SMS, and in-app channels.
Architecture
| Layer | Location |
|---|---|
| Notification service layer | backend/src/lib/notifications/ (notification-service, channel-resolver, renderers, portal-notifications) |
| BullMQ job processor | backend/src/lib/jobs/processors/notifications.ts (routes email/SMS jobs + scheduled jobs) |
| Email templates | backend/src/lib/email-templates/ |
| SMS module | backend/src/lib/sms/ |
| Portal notifications | portalNotifications DB table |
| Notification bell | PortalNotificationBell component |
Channels
| Channel | Provider | Implementation |
|---|---|---|
| Resend Email | backend/src/lib/email-templates/ | |
| SMS | MessageBird SMS (provider now branded “Bird”, BIRD_API_KEY) | backend/src/lib/sms/ |
| In-app (portal) | Internal | portalNotifications table + PortalNotificationBell |
Notification Intents
Current intents (backend/src/lib/notifications/types.ts):
| Intent | Channel(s) | Trigger |
|---|---|---|
password_reset, email_verification, magic_link, welcome_email | Authentication flows | |
phone_verification, 2fa_code | SMS | Phone/2FA verification |
document_reminder, new_document_requests | Email, SMS | Document Obtaining requests and overdue reminders |
rejection_bundle | Consolidated Document Review rejections (10-min bundling window) | |
help_response | Email, in-app | Portal help chat responses |
generic_notification | Any | Ad-hoc notifications |
Background Processing
Notifications are processed asynchronously via Background Jobs (BullMQ notification queue). This prevents notification delivery from blocking API responses and provides retry capabilities for transient failures. The processor at backend/src/lib/jobs/processors/notifications.ts dispatches email/SMS jobs and delegates scheduled work to sibling processors: document-reminder, reminder-scheduler, rejection-bundle, escalation-scheduler, token-cleanup, entra-sync, and the billing-* jobs.
Document Obtaining Reminders
Dedicated tables track reminder state:
| Table | Purpose |
|---|---|
documentObtainingReminderHistory | Tracks when reminders were sent per document request |
documentObtainingNotifications | Configures reminder schedules and escalation rules |
See Document Obtaining for the full document collection workflow.
Email Templates
Email templates at backend/src/lib/email-templates/ are HTML templates with placeholder interpolation. Template selection and content are managed through the Admin Dashboard (email template settings).
SMS Delivery
SMS messages are sent via MessageBird SMS (the provider rebranded to “Bird”; the backend reads BIRD_API_KEY) with SMS_CATCH_ALL_PHONE_NUMBERS for development/staging environments (prevents sending real SMS during testing).
Email i18n
Email templates are bilingual: each template takes a language: 'de' | 'en' parameter and renders per-language content blocks at the backend boundary.
In-App Notifications
The portalNotifications table stores in-app notifications for Portal users. The PortalNotificationBell component displays unread count and notification list.
Related
- Portal — in-app notification delivery
- Document Obtaining — document reminder notifications
- Background Jobs — async notification processing
- Resend Email — email delivery provider
- MessageBird SMS — SMS delivery provider
- Admin Dashboard — email template configuration
- Appointments — appointment notification triggers