Skip to main content

UniConnect Notification Service

Overview​

The UniConnect Notification System provides real-time in-app alerts, browser web push, and workflow-driven messaging across the UniConnect platform. It is designed around an event-agnostic, config-driven architecture that natively integrates with:

  • Moleculer Microservices: Handled by notification.service.js and push.service.js.
  • WebSocket Gateway: Real-time push using { entity: "NOTIFICATION", action: "...", payload: { ... } } through websocket.service.js.
  • UniConnect Workflows: Action nodes in WorkflowRegistry enabling automated notifications on CRM/ticket events.
  • Relational & Scoped Targeting: Delivering alerts based on record assignments, group memberships, and role hierarchies.

For complete architectural decisions, see RFC-012: In-App Notifications & Topic Orchestration.


1. Core Architecture​


2. Data Model (prisma/schema.prisma)​

enum NotificationType {
INFO
SUCCESS
WARNING
ERROR
ALERT
}

model Notification {
id Int @id @default(autoincrement())
userId Int @map("user_id")
title String @db.VarChar(255)
description String @db.Text
image String? @db.Text // Icon, badge, or avatar
type NotificationType @default(INFO)
topic String? @db.VarChar(100)
callToAction Json? @map("call_to_action")
// Structure: { type: "navigate", label: "View Ticket", url: "/crm/tickets/101", target: "_self" }

isRead Boolean @default(false) @map("is_read")
readAt DateTime? @map("read_at") @db.Timestamptz(3)

metadata Json? @map("metadata")
createdById Int? @map("created_by_id")
createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3)
updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3)

user User @relation(fields: [userId], references: [id], onDelete: Cascade)

@@index([userId, isRead, createdAt(sort: Desc)])
@@index([userId, topic])
@@index([createdAt(sort: Desc)])
@@map("notifications")
}

model UserNotificationPreference {
id Int @id @default(autoincrement())
userId Int @map("user_id")
topic String @db.VarChar(100)
isSubscribed Boolean @default(true) @map("is_subscribed")

inApp Boolean @default(true) @map("in_app")
webPush Boolean @default(false) @map("web_push")
email Boolean @default(false) @map("email")
sms Boolean @default(false) @map("sms")

createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3)
updatedAt DateTime @default(now()) @updatedAt @map("updated_at") @db.Timestamptz(3)

user User @relation(fields: [userId], references: [id], onDelete: Cascade)

@@unique([userId, topic])
@@index([userId])
@@map("user_notification_preferences")
}

3. Microservice Actions (notification.service.js)​

ActionREST EndpointDescription
notification.sendInternal / RPCCreates notification record, resolves audience, and pushes over WebSocket (sendToUser).
notification.listGET /api/v1/notification/listPaginated notifications for logged-in user with isRead and topic filters.
notification.unreadCountGET /api/v1/notification/unread-countReturns badge count of unread notifications for current user.
notification.markAsReadPOST /api/v1/notification/mark-readMarks a single notification as read and broadcasts READ_UPDATED to other open tabs.
notification.markAllAsReadPOST /api/v1/notification/mark-all-readMarks all notifications for user as read and broadcasts READ_ALL_UPDATED.

4. WebSocket Payload Protocol​

In-app notifications use UniConnect's standard event envelope:

Real-Time In-App Alert​

{
"entity": "NOTIFICATION",
"action": "CREATED",
"payload": {
"id": 142,
"title": "Lead Assigned",
"description": "Lead #4928 John Doe has been assigned to you.",
"image": "/assets/avatar.png",
"type": "INFO",
"callToAction": {
"type": "navigate",
"label": "Open Lead",
"url": "/crm/leads/4928",
"target": "_self"
},
"isRead": false,
"createdAt": "2026-10-09T09:30:00Z"
}
}

Multi-Tab Read Status Sync​

{
"entity": "NOTIFICATION",
"action": "READ_UPDATED",
"payload": {
"id": 142,
"isRead": true,
"readAt": "2026-10-09T09:32:00Z"
}
}

5. Workflow Automation & Topic Scoping​

5.1 Workflow Actions in WorkflowRegistry​

  • notification.sendInApp: Sends notifications at any workflow stage with dynamic placeholder resolution ({{ticket.id}}, {{lead.name}}, {{assignedTo}}).
  • notification.manageSubscription: Automatically subscribes or unsubscribes agents as records progress through their lifecycle (e.g. subscribe on ticket assignment, unsubscribe on ticket closure).

5.2 Relevance & Audience Scoping​

Notifications are filtered to avoid broadcasting noise to irrelevant users:

  • Direct Assignee: Evaluated from entity attributes (e.g. assignedToId).
  • Group Members: Resolved from the UserGroup table using groupId.
  • Role Supervisors: Resolved for supervisory roles with administrative scope.
  • Topic Preferences: Filtered against UserNotificationPreference so users can opt out of non-critical topics.

6. Frontend Components (uc-enterprise-web)​

  1. NotificationBell.tsx in DashboardHeader:
    • Displays unread badge count (<Badge count={unreadCount} overflowCount={99}>).
    • Clicking opens an interactive Ant Design <Popover> or slide-out <Drawer>.
  2. Notification Popover / Center:
    • Filter tabs: All and Unread.
    • Header action: Mark all as read.
    • Each item includes avatar/icon, title, description, timestamp, CTA button, and read toggle.
  3. Floating Toast Alert:
    • Displays a brief slide-in toast when high-priority notifications arrive while the user is actively working.

7. Implementation Roadmap​

PhaseTarget ScopeKey Tasks
Phase 1In-App MVPPrisma migration, notification.service.js, WebSocket integration, Header NotificationBell.tsx, Redux notificationSlice.
Phase 2WorkflowsRegister notification.sendInApp in WorkflowRegistry, dynamic template placeholder mapping, CTA URL builders.
Phase 3Topics & ScopingUserNotificationPreference model, AudienceResolver (Assignee, UserGroup, Roles), User Settings UI.
Phase 4OmnichannelUnified dispatcher routing across In-App, Browser Web Push (push.service.js), Email, SMS, and WhatsApp.