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.jsandpush.service.js. - WebSocket Gateway: Real-time push using
{ entity: "NOTIFICATION", action: "...", payload: { ... } }throughwebsocket.service.js. - UniConnect Workflows: Action nodes in
WorkflowRegistryenabling 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)
| Action | REST Endpoint | Description |
|---|---|---|
notification.send | Internal / RPC | Creates notification record, resolves audience, and pushes over WebSocket (sendToUser). |
notification.list | GET /api/v1/notification/list | Paginated notifications for logged-in user with isRead and topic filters. |
notification.unreadCount | GET /api/v1/notification/unread-count | Returns badge count of unread notifications for current user. |
notification.markAsRead | POST /api/v1/notification/mark-read | Marks a single notification as read and broadcasts READ_UPDATED to other open tabs. |
notification.markAllAsRead | POST /api/v1/notification/mark-all-read | Marks 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
UserGrouptable usinggroupId. - Role Supervisors: Resolved for supervisory roles with administrative scope.
- Topic Preferences: Filtered against
UserNotificationPreferenceso users can opt out of non-critical topics.
6. Frontend Components (uc-enterprise-web)
NotificationBell.tsxinDashboardHeader:- Displays unread badge count (
<Badge count={unreadCount} overflowCount={99}>). - Clicking opens an interactive Ant Design
<Popover>or slide-out<Drawer>.
- Displays unread badge count (
- 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.
- Floating Toast Alert:
- Displays a brief slide-in toast when high-priority notifications arrive while the user is actively working.
7. Implementation Roadmap
| Phase | Target Scope | Key Tasks |
|---|---|---|
| Phase 1 | In-App MVP | Prisma migration, notification.service.js, WebSocket integration, Header NotificationBell.tsx, Redux notificationSlice. |
| Phase 2 | Workflows | Register notification.sendInApp in WorkflowRegistry, dynamic template placeholder mapping, CTA URL builders. |
| Phase 3 | Topics & Scoping | UserNotificationPreference model, AudienceResolver (Assignee, UserGroup, Roles), User Settings UI. |
| Phase 4 | Omnichannel | Unified dispatcher routing across In-App, Browser Web Push (push.service.js), Email, SMS, and WhatsApp. |