Blend

Overview

The Notifications feature provides a comprehensive user notification system supporting both individual notifications and broadcast messages. It includes read/unread tracking, archiving, batch operations, search functionality, and admin controls for composing and sending notifications to users.

Key Features

Notification Management

User Notifications: Individual notifications for specific users
Broadcast Messaging: Send notifications to multiple users
Read/Unread Tracking: Track which notifications users have read
Archive System: Archive old or completed notifications
Action URLs: Link notifications to specific pages or actions

Notification States

Unread: New notifications that haven't been read (readAt: null)
Read: Notifications that have been viewed (readAt: DateTime)
Archived: Notifications moved to archive (archived: true)
Active: Non-archived notifications (archived: false)

User Interface

Tab Navigation: Switch between Unread, All, and Archived views
Batch Operations: Select multiple notifications for bulk actions
Mark as Read: Single or batch mark as read
Archive/Unarchive: Move notifications between active and archived
Search: Full-text search across notification content
Pagination: Handle large numbers of notifications efficiently

Admin Features

Compose Interface: Create and send notifications
Broadcast Messaging: Send to multiple users simultaneously
Admin-Only Access: Notification creation restricted to admin users
Delivery Tracking: See which users received notifications

Database Models

Notification Model

model Notification {
  id              String    @id @default(cuid())
  createdAt       DateTime  @default(now())
  updatedAt       DateTime  @updatedAt
  tenantId        String
  tenant          Tenant    @relation(fields: [tenantId], references: [id])
  userId          String
  user            User      @relation(fields: [userId], references: [id])
  createdByUserId String?
  createdByUser   User?     @relation("createdByUser", fields: [createdByUserId], references: [id])
  title           String
  message         String    @db.NVarChar(max)
  type            String    @default("info")  // info, success, warning, error
  actionUrl       String?
  actionText      String?
  readAt          DateTime?
  archived        Boolean   @default(false)
}

Routes

User Routes

/app/{tenant}/notifications - View notifications inbox

Features:

Tabs for Unread, All, and Archived
Batch selection and operations
Mark as read functionality
Archive/unarchive actions
Delete notifications
Search functionality
Pagination support

Admin Routes

/app/{tenant}/settings/notifications?add=true - Compose new notification

Admin compose features:

Send to specific users
Broadcast to multiple users
Set notification type (info, success, warning, error)
Add action URL and action text
Preview before sending

Notification Types

Type Indicators

Notifications can be categorized by type for visual distinction:

info: Informational notifications (default)
success: Success or completion messages
warning: Warning or attention-required messages
error: Error or critical notifications

Type determines visual styling (color, icon) in the UI.

Notification Operations

Creating Notifications

await createNotification({
  tenantId,
  userId,
  title,
  message,
  type: "info",
  actionUrl: "/app/tenant/some-page",
  actionText: "View Details",
  createdByUserId,
});

Marking as Read

await markNotificationAsRead(notificationId);

Updates readAt to current timestamp.

Archiving

await archiveNotification(notificationId);

Sets archived: true to move notification to archived tab.

Unarchiving

await unarchiveNotification(notificationId);

Sets archived: false to restore notification to active inbox.

Deleting

await deleteNotification(notificationId);

Permanently removes notification from database.

User Interface Tabs

Unread Tab

Shows notifications where:

readAt is null
archived is false

Default tab when user visits notifications page.

All Tab

Shows all notifications where:

archived is false

Includes both read and unread notifications.

Archived Tab

Shows notifications where:

archived is true

Includes notifications user has archived for later reference.

Batch Operations

Batch Mark as Read

Select multiple unread notifications
Click "Mark as Read" button
All selected unread notifications updated
Selection cleared automatically

Implementation:

const handleBatchMarkAsRead = () => {
  selectedIds.forEach((id) => {
    const item = data.items.find((n) => n.id === id);
    if (item && !item.readAt) {
      onMarkAsRead(id);
    }
  });
  setSelectedIds([]);
};

Batch Archive

Select multiple active notifications
Click "Archive" button
All selected notifications archived
Selection cleared automatically

Search Functionality

Search across:

Notification title
Notification message
Notification type
Action text
Creation date

Search is URL-based with ?q= parameter for deep linking.

Pagination

Notifications support pagination for performance:

const { items, pagination } = await getNotificationsWithPagination({
  tenantId,
  userId,
  pagination: { page, pageSize },
  filters: {
    read: unreadTab ? false : undefined,
    archived: archivedTab ? true : false,
    search,
  },
});

Pagination data includes:

Current page
Page size
Total items
Total pages

Notification Delivery

Broadcast Notifications

Admin users can broadcast to multiple users:

Compose notification in admin interface
Select multiple user recipients
Set title, message, type, and action details
Click "Send"
Individual notification created for each recipient

Individual Notifications

Send notification to specific user:

Target single user by userId
Notification appears in user's inbox
User receives in-app notification

Access Control

Permission Requirements

View Notifications: All authenticated users
Create Notifications: Admin users only (canCreate flag)
Compose Interface: Admin route with ?add=true parameter
Batch Operations: Available to all users for their own notifications

Notification Filtering

Users only see notifications where:

tenantId matches their tenant
userId matches their user ID
Tenant isolation enforced at database level

Best Practices

Clear Titles: Use concise, descriptive notification titles
Action URLs: Provide actionable links when relevant
Type Selection: Choose appropriate notification type for context
Read Management: Encourage users to mark notifications as read
Archive Strategy: Archive old or completed notifications
Search Usage: Use search to find specific notifications
Batch Operations: Use batch operations for managing multiple notifications
Admin Compose: Use admin interface for broadcast announcements

Common Operations

View Unread Notifications

Navigate to /app/{tenant}/notifications
Default view shows unread notifications
Click on notification to mark as read (optional)
Click action link if provided

Mark Notification as Read

View notification in list
Click "Mark as Read" button or link
Notification moves to read state
readAt timestamp recorded

Archive Notifications

Select notification(s) from active inbox
Click "Archive" button
Notifications move to Archived tab
Can be unarchived later if needed

Search Notifications

Enter search term in search box
URL updates with ?q=search-term
Results filter to matching notifications
Clear search to show all notifications

Compose and Send (Admin)

Navigate to /app/{tenant}/settings/notifications?add=true
Enter notification details:
- Title
- Message
- Type (info, success, warning, error)
- Action URL and text (optional)
Select recipient users
Click "Send" or "Compose"
Notifications delivered to selected users