Notifications Service

┌─────────────────┐
│   Any Service   │
│ (triggers event)│
└────────┬────────┘
         │
         ▼
┌────────────────────────────────────────┐
│        Notification Dispatch           │
│            (via Tasks)                 │
│                                        │
│  WYSIWYG Notification Configuration    │
│        (see Platform Admin)            │
└────────┬───────────────────────────────┘
         │
    ┌────┴─────────┬──────────┬──────────┬──────────┐
    ▼              ▼          ▼          ▼
┌──────────┐  ┌──────────┐ ┌──────────┐ ┌──────────┐
│  Email   │  │  Push    │ │  In-App  │ │ Channels │
│(Template)│  │ (Cloud   │ │ (Store)  │ │(Webhooks)│
│          │  │Messaging)│ │          │ │          │
└──────────┘  └──────────┘ └──────────┘ └──────────┘

INotification structure:
  - Unique ID (group_name format)
  - Group, name, and sentWhen metadata
  - Per-channel configuration (email, push, inApp)
  - Per-channel thresholds and enable/disable flags
  - Scheduled nudge definitions
 
NotificationDispatchService:
  - Sends to task queue with 2-minute deduplication window
  - Supports scheduled delivery via scheduleAt parameter
  - Automatic dedup key generation from request data
  - Separate queues for requests, resends, nudges

NotificationSagas orchestrate:
  - SendEmailNotificationCommand (if email.notificationOn)
  - SendInAppNotificationCommand (if inApp.notificationOn)
  - SendPushNotificationCommand (if push.notificationOn)
  - SendNudgeNotificationCommand (if nudges defined)
 
Each saga:
  - Filters based on channel configuration
  - Fires independent command handlers
  - Runs in parallel for performance
  - Isolated failures per channel

ContentPreparationService handles:
  - Template compilation with unique cache IDs
  - Template registration in engine cache
  - Token replacement from notification data
  - Tenant data injection (company name, platform name, year)
  - URL building from routes + tenant bootstrap host
  - Logo image URL replacement in HTML
  - Special character encoding/decoding
 
Template token types:
  - Data tokens: {{field}} from request data
  - Tenant tokens: {emailCompanyName}, {emailPlatformName}
  - Email tokens: {{messageText}}, {{callToActionText}}
  - Route tokens: URL generation from path + host

ThresholdService provides:
  - Separate thresholds for email, push, inApp, Slack, Teams
  - Entity ID override support for custom grouping
  - Default 60-second minimum threshold
  - Configurable per-notification thresholds
 
NotificationStoreRepository implements:
  - Transactional threshold checking
  - Query for most recent notification by entityId + notificationId
  - Time-based threshold comparison
  - Automatic store creation on threshold pass
  - Prevents duplicate sends within threshold window

NotificationUserService handles:
  - User existence validation
  - Disabled user blocking
  - User preference fetching with caching
  - Non-opt-out notification whitelist
  - Tenant bootstrap resolution
  - Auth tenant validation
 
SendPushNotificationHandler checks:
  - Threshold validation
  - Suppress flag enforcement
  - User opt-out status
  - Push preferences enabled check
 
SendEmailNotificationHandler validates:
  - Email address availability
  - User or non-user request type
  - Email preferences enabled
  - Non-opt-out override application

TokenService provides:
  - Token registration with client type (Web, Mobile)
  - Upsert logic for token updates
  - Last-used timestamp tracking
  - Transaction-safe token removal
 
SendPushNotificationHandler orchestrates:
  - Query all tokens for user
  - Send via cloud messaging service
  - Collect failed token list
  - Delete failed tokens automatically
  - Update successful tokens with last-used timestamp
  - Increment badge count per user

SendNudgeNotificationHandler:
  - Schedules task for each nudge in configuration
  - Calculates scheduledTime from offset in days
  - Sends to separate nudge queue
  - Marks request with nudge flag
 
NotificationsController filters:
  - Checks nudge conditions via injected handlers
  - Evaluates condition functions with nudge context
  - Blocks nudge if condition returns false
  - Supports custom condition logic per notification
 
Nudge configuration:
  - notificationId: ID of nudge notification config
  - offset: Days before sending (0 = immediate)

EmailNotificationsService orchestrates:
  - Fetch email template by ID
  - Replace logo image placeholder with tenant URL
  - Inject messageText and callToActionText
  - Build URLs from routes + tenant host
  - Render templates with tenant data
  - Replace tenant tokens in subject and fromTitle
 
Template data includes:
  - Request data (dynamic notification content)
  - Tenant data (company name, platform name)
  - Current year for copyright
  - Generated URLs for call-to-action links
  - Email logo URL from tenant bootstrap

SlackNotificationService:
  - Uses Slack Block Kit format
  - Header block with subject
  - Section block with text
  - Divider for visual separation
  - Supports markdown formatting
  - Fetches webhook URL from secrets
 
TeamsNotificationService:
  - Uses legacy MessageCard format
  - Title and text fields
  - Schema.org extensions context
  - Fetches webhook URL from secrets
 
WebhookNotificationService base:
  - JSON body preparation
  - RestClient integration
  - URL parsing and origin extraction
  - Secret management via SecretsService

SendInAppNotificationHandler:
  - Creates IAppNotification document
  - Includes notification data + message info
  - Sets viewed: false for new notifications
  - Assigns unique appNotificationId
  - Links to notification type (config.id)
  - Increments user's in-app notification count
 
AppNotificationRepository:
  - Stores notifications in dedicated collection
  - Indexed by userId for efficient queries
  - Supports viewed status updates
  - Enables notification history retrieval
 
UserNotificationConfigRepository:
  - Tracks pushNotificationCount
  - Tracks inAppNotificationCount
  - Provides badge count for push delivery

CloudFunctionGenerator creates:
  - APP_NOTIFICATION_CREATED (onCreate trigger)
  - NOTIFICATION_DELETED (onDelete trigger)
 
Event flow:
  - Database trigger fires on document change
  - Event published to topic
  - Topic handler routes to task queue
  - Task worker processes event
 
NotificationDeletedEvent triggers:
  - RemoveNudgeNotificationCommand
  - Cancels scheduled nudges for deleted notification

Queue structure:
  - NOTIFICATION_REQUEST: Primary notification dispatch
  - NOTIFICATION_RESEND_REQUEST: Resend with reduced threshold
  - NOTIFICATION_NUDGE_REQUEST: Scheduled follow-ups
  - NOTIFICATION_CHANNEL_REQUEST: Slack/Teams delivery
  - APP_NOTIFICATION_REQUEST: Direct in-app notifications
  - NOTIFICATION_TEST_REQUEST: Testing notifications
  - NOTIFICATION_DELETED: Cascade cleanup
  - USER_EVENTS: User lifecycle events
 
Queue benefits:
  - Independent scaling per queue
  - Isolated failure domains
  - Priority-based processing
  - Dedicated error handling

EmailService:
  - Fetches Mailgun API key from secrets
  - Fetches Mailgun domain from secrets
  - NodeMailgun client initialization
  - Supports single or multiple recipients
  - Custom variables for template tracking
  - From email and from title configuration
  - Unsubscribe link control
 
Email parameters:
  - toEmail: Single address or array
  - fromEmail: Required by mail provider
  - fromTitle: Display name for sender
  - subject: Rendered from template
  - html: Fully rendered HTML content
  - templateId: Tracking variable (v:id)

TokenController endpoints:
  - POST /notifications-token: Register push token
  - POST /notifications-token/logout: Remove token
 
TokenService operations:
  - createToken: Upsert with client type and timestamp
  - removeUserFromToken: Transaction-safe removal
  - Validates userId matches before deletion
 
Authentication:
  - @RequireCustomClaim('appUserId')
  - Extracts userId from JWT claims
  - Validates user authorization per token