🔔 Notification & Logging Standards

Overview

The RABS notification system provides a unified pipeline for delivering system events to users as toasts, badge updates, sounds, and log entries. All new features must use the DB2 pipeline (syslog schema). The legacy DB1 logging path exists for backward compatibility only.

Backend Pipeline (DB2)

The modern notification pipeline flows through the syslog schema:

emitEntries.emitEntry()
    ↓
syslog.entries (persisted)
    ↓
bus.emit('syslog.entry.created')
    ↓
notifications-interpreter
    ↓
Expand targets (users, roles, curated)
    ↓
Determine tile routing via context.kind
    ↓
Insert → syslog.notifications
    ↓
SSE broadcast to connected clients

Legacy Pipeline (DB1)

emitLog.emitLog() → admin.system_logs

Do NOT use the legacy pipeline for new features. It exists solely for backward compatibility with older modules.

Key Backend Files

File	Purpose
emit-entries.js	emitEntry() — primary entry point for all new notifications
notifications-interpreter.js	Expands targets, determines routing, inserts notifications
emit-log-db2.js	DB2 syslog entry writer
logger.js	Structured console/file logging utility

emitEntry() Call Shape

Every notification originates from a call to emitEntry() with this structure:

{
  platform,          // e.g. 'admin', 'bot'
  type,              // event type identifier
  delivery,          // 'silent' | 'normal' | 'push' | 'alert'
  bucket_slug,       // context bucket for grouping
  targets: {
    users,           // array of user IDs
    roles,           // array of role slugs
    curated          // custom target list
  },
  message,           // human-readable notification text
  context: {
    kind,            // routing key — determines tile, sound, behaviour
    // ...additional context fields
  }
}

Frontend Notification Hub

SSE Stream (notifications-hub.js)

The frontend connects to a Server-Sent Events stream at:

GET /api/v1/notifications/stream

Three event types are emitted:

Event	Purpose
badge	Update a tile's unread count
toast	Display a toast notification
log	Append to the activity log

Toast System (error-handler.js)

Toast Functions

Function	Default Duration	Use Case
showToast(options)	Configurable	General-purpose toast
showSuccess(message)	Default	Confirm successful operations
showError(message)	7 seconds	Display error messages
showWarning(message)	6 seconds	Display warning messages
showInfo(message)	Default	Informational messages

Toast Options

{
  type,         // 'success' | 'error' | 'warning' | 'info'
  duration,     // milliseconds (0 = sticky)
  title,        // bold heading text
  dismissible,  // boolean — show close button
  icon,         // Bootstrap icon class
  onClose       // callback when dismissed
}

Quick Access Tiles

The header displays a 3×2 grid of quick-access tiles. Each tile shows a badge count driven by the context.kind field of incoming notifications.

Tile	Icon	Badge Source (context.kind)
Calendar	calendar4	calendar.*
Inbox	envelope	email.*
Profile	person-circle	profile*
Tasks	list-task	task*
Messenger	chat-dots	chat.*
Comms	telephone	comms.*

context.kind Routing

The context.kind field determines which tile receives the badge update and, where applicable, the notification sound:

Kind Pattern	Routed Tile	Notes
chat.*	Messenger	All chat-related events
comms.*	Comms	Phone, SMS, voicemail
email.*	Inbox	Email receive/send events
calendar.*	Calendar	Appointments, reminders
profile*	Profile	Profile updates, mentions
task*	Tasks	Task assignments, completions
forum.*	Tasks	Forum posts route to tasks tile
auth.*	Bell only	Login, session events — no tile
presence.*	Toast only	Online/offline — no tile or badge

Delivery Modes

Four delivery modes control how prominently a notification surfaces to the user:

Mode	Toast	Bell	Tile Badge	Sound	Notes
silent	No	No	No	Yes	Sound only — background awareness
normal	5 seconds	Yes	Yes	Yes	Standard notification
push	Sticky	Yes	Yes	Yes	Requires manual dismiss
alert	Sticky	Yes	Yes	Yes	Requires explicit acknowledgement

Sound Mapping

Thirteen notification sounds are available, selected based on context.kind and event type:

Sound File	Trigger Context
message_mention.wav	Direct mention in chat
message_in.wav	New chat message
sms_in.mp3	Incoming SMS
email.mp3	New email received
phone1.wav	Incoming call
error.wav	Error notifications
success.wav	Success confirmations
presence_online.wav	User came online
birthday.wav	Birthday notification
notification.wav	Generic notification
alert.wav	Alert-level events
task_complete.wav	Task completed
reminder.wav	Scheduled reminders