Notification Service & Delivery

Notification Service & Delivery

The NotificationService is the central orchestrator for all notifications in NexusRMS. It creates notification records, determines delivery channels, respects user preferences and quiet hours, and dispatches through multiple channels including in-app, email, SMS, and push.

NotificationService Methods

Method	Description
send(user, type, data, options)	Creates a notification record and triggers delivery across all enabled channels for the user
sendToMany(users, type, data)	Bulk sends the same notification to multiple users efficiently
getFeed(user, perPage=20, filters)	Returns a paginated notification feed with optional type, read status, and date filters
getUnreadCount(user)	Returns the count of unread notifications for badge display
getRecent(user, limit=10)	Returns the latest notifications for the dropdown panel
groupNotifications(notifications)	Groups related notifications by group_key (e.g. "3 new comments on Project #412")
processSnoozedNotifications()	Cron job that delivers snoozed notifications once quiet hours end
sendPlatformAnnouncement(data)	Broadcasts a system-wide announcement to all connected users
getStatistics(user, start, end)	Returns notification statistics for a given date range

Notification Model Fields

Field	Type	Description
user_id	integer	The recipient user
type	string	Notification type (e.g. project.created, invoice.overdue)
notifiable_type	string	Polymorphic model class
notifiable_id	integer	Polymorphic model ID
title	string	Display title
body	text	Notification body text
icon	string	MDI icon name
color	string	Vuetify colour name
data	JSON	Contains action_url, priority, and action_label
group_key	string	Groups related notifications together
thread_id	string	Links to a discussion thread
is_grouped	boolean	Whether this notification has been collapsed into a group
read_at	timestamp	When the notification was read (null if unread)
archived_at	timestamp	When the notification was archived
snoozed_until	timestamp	Delivery deferred until this time
channels	array	Delivery channels used (in_app, email, sms, push)
email_sent_at	timestamp	When the email was dispatched
email_opened_at	timestamp	When the email tracking pixel was loaded
sms_sent_at	timestamp	When the SMS was dispatched
push_sent_at	timestamp	When the push notification was sent

Notification Actions

• markAsRead — sets read_at to the current timestamp
• markAsUnread — clears read_at back to null
• archive — sets archived_at, removing the notification from the active feed
• unarchive — clears archived_at, restoring the notification to the feed
• snooze(until) — sets snoozed_until to defer delivery to a future time
• isSnoozed — returns true if snoozed_until is in the future

Computed Attributes

• time_ago — human-readable relative timestamp (e.g. "5 minutes ago")
• action_url — extracted from the data JSON, links to the relevant resource
• action_label — button text, defaults to "View" if not specified
• priority — extracted from data JSON, defaults to "normal"

Query Scopes

• unread() — where read_at is null
• read() — where read_at is not null
• archived() — where archived_at is not null
• active() — not archived and not currently snoozed
• ofType(type) — filters by notification type prefix

NotificationDeliveryService

The delivery service orchestrates multi-channel dispatch while respecting user preferences:

1. In-app — broadcasts via WebSocket using the NotificationCreated event for instant display
2. Email — dispatched immediately or batched into a digest depending on user preference (handled by EmailNotificationService)
3. SMS — sent via Twilio for high and urgent priority notifications only (handled by SMSNotificationService)
4. Push — browser push notifications and PWA push for mobile devices (handled by PushNotificationService)

Priority Levels

Priority	Colour	Behaviour
Urgent	Error red	Bypasses quiet hours, triggers all enabled channels immediately
High	Warning orange	Respects quiet hours, triggers all enabled channels
Normal	Primary blue	Respects quiet hours, standard delivery
Low	Info light blue	Respects quiet hours, in-app only unless user opts in