Skip to main content

Notification System - Technical Implementation

Note: This document covers the technical implementation of the notification system. For user-facing documentation, see the Notification System User Guide.

Important: The notification system is a feature of toto-bo (backoffice), not a standalone system. It provides real-time notifications for backoffice users.

Update (Aug 2025)

  • Simplified notifications modal: compact header, All/Unread/Urgent filters, mark-all-read, click-to-mark-read.
  • In-app vs email policy: collaborator invites/resets are sent by email; BO-only events (tickets, updates) use in‑app notifications.
  • RBAC: notifications APIs enforce owner or admin for read/mark/delete; mark-all-read defaults to requester.
  • Sidebar bell uses real counts; list loads via /api/notifications?userEmail=. Ordering falls back safely if missing indexes.
  • Ticket events: creating/updating tickets produce notifications; assignment notifies the assignee.

🎯 Overview​

The notification system is a feature of the toto-bo (backoffice) platform, providing real-time notifications, role-based delivery, and advanced management capabilities for backoffice users.

🏗️ Architecture​

Core Components​

  1. Notification Types System (src/lib/notificationTypes.ts)

    • 24 different notification types
    • Template-based configuration
    • Role-based delivery rules
    • Priority and expiration settings

  2. Notification Service (src/lib/notificationService.ts)

    • Singleton pattern implementation
    • Firebase integration
    • Audit logging integration
    • Auto-expiration handling

  3. Real-time Hook (src/hooks/useRealTimeNotifications.ts)

    • WebSocket-ready architecture
    • Auto-refresh capabilities
    • State management
    • Error handling

  4. Toast System (src/components/ui/ToastNotifications.tsx)

    • Immediate feedback
    • Multiple notification types
    • Action buttons
    • Auto-dismiss functionality

📋 Notification Types​

Case Management​

  • case_created - New case created
  • case_updated - Case information updated
  • case_urgent - Urgent case requiring attention
  • case_completed - Case successfully completed

Financial​

  • donation_received - New donation received
  • donation_failed - Donation payment failed
  • payment_processed - Payment successfully processed
  • payment_failed - Payment processing failed

User Management​

  • guardian_registered - New guardian joined
  • guardian_updated - Guardian profile updated
  • partner_joined - New partner organization
  • collaborator_invited - Collaborator invited
  • collaborator_joined - Collaborator joined team
  • collaborator_left - Collaborator left team

Security & System​

  • security_alert - Security event detected
  • system_maintenance - System maintenance
  • audit_log_created - New audit log entry
  • permission_granted - New permissions granted
  • permission_revoked - Permissions revoked

Support & Analytics​

  • support_ticket_created - New support ticket
  • support_ticket_updated - Support ticket updated
  • support_ticket_resolved - Support ticket resolved
  • report_generated - New report ready
  • analytics_ready - Analytics data updated

🔐 Security Features​

Role-Based Access Control​

  • Owner or admin can read/modify notifications (API-enforced)
  • Permission-based visibility in UI
  • Admin-only destructive actions (delete)
  • Audit logging best-effort in ticket/collaborator flows

Permission Matrix​

// Who receives which notifications
case_created: ["admin", "staff"]
case_urgent: ["admin", "staff"]
donation_received: ["admin", "staff"]
security_alert: ["admin"]
support_ticket_created: ["admin", "staff"]

🎨 User Interface​

Enhanced Notification Center​

  • Real-time updates
  • Priority-based filtering
  • Action buttons with deep linking
  • Statistics dashboard
  • Bulk operations (mark all read)

Toast Notifications​

  • Immediate feedback
  • Priority-based styling
  • Action buttons
  • Auto-dismiss with configurable duration
  • Urgent notifications (no auto-dismiss)

Notification Settings Page​

  • Per-type configuration
  • Channel preferences (in-app, email, push)
  • Frequency settings
  • Quiet hours configuration

🔧 API Endpoints​

Core Endpoints​

  • GET /api/notifications — Fetch notifications. Filters: userEmail (preferred), type, read, priority, limit, offset. Owner/admin only.
  • POST /api/notifications — Create notification (server-side use only).
  • POST /api/notifications/[id]/mark-read — Mark as read (owner/admin only).
  • POST /api/notifications/mark-all-read — Mark all as read for requester (owner/admin; defaults to requester email).
  • DELETE /api/notifications/[id] — Delete notification (owner/admin only).

Features​

  • Role-based access control
  • Comprehensive filtering
  • Pagination support
  • Real-time updates
  • Audit logging

📊 Statistics & Analytics​

Notification Stats​

  • Total notifications count
  • Unread notifications count
  • Priority-based breakdown
  • User-specific statistics
  • Real-time updates

Management Features​

  • Bulk operations
  • Filtering by type, priority, status
  • Search functionality
  • Export capabilities

🚀 Real-time Features​

WebSocket Integration​

  • Live notification updates
  • Automatic reconnection
  • Error handling
  • Connection status monitoring

Auto-refresh​

  • 5-minute intervals
  • User activity detection
  • Background sync
  • Offline support

🎯 Key Features​

1. Comprehensive Type System​

  • 24 notification types
  • Template-based configuration
  • Role-based delivery
  • Priority management

2. Real-time Updates​

  • WebSocket-ready architecture
  • Live notification delivery
  • Auto-refresh capabilities
  • Connection management

3. Advanced UI/UX​

  • Enhanced notification center
  • Toast notifications
  • Settings management
  • Statistics dashboard

4. Security & Permissions​

  • Role-based access control
  • Permission guards
  • Audit logging
  • Secure API endpoints

5. Management Tools​

  • Notification settings page
  • Bulk operations
  • Filtering and search
  • Export capabilities

🔄 Integration Points​

Authentication​

  • NextAuth integration
  • Session-based notifications
  • Role-based filtering

RBAC System​

  • Permission guards
  • Role-based delivery
  • Access control

Audit System​

  • Action logging
  • Notification tracking
  • Security monitoring

Database​

  • Firebase Firestore
  • Real-time listeners
  • Offline support

📈 Performance Optimizations​

Caching​

  • Notification state caching
  • Template caching
  • Statistics caching

Pagination​

  • Lazy loading
  • Infinite scroll
  • Efficient queries

Real-time​

  • WebSocket optimization
  • Connection pooling
  • Error recovery

🧪 Testing​

Test Coverage​

  • ✅ Notification types validation
  • ✅ Service method testing
  • ✅ API endpoint testing
  • ✅ Component testing
  • ✅ Permission testing
  • ✅ RBAC integration
  • ✅ File structure validation

Test Script​

node scripts/test-notifications.js

🚀 Deployment Ready​

Production Features​

  • Error handling
  • Logging
  • Monitoring
  • Security
  • Performance optimization

Configuration​

  • Environment variables
  • Feature flags
  • Customization options

📝 Usage Examples​

Creating Notifications (server-side)​

import { createNotification } from '@/lib/notifications';

await createNotification({
  userEmail: 'admin@example.com',
  type: 'support_ticket_created',
  title: 'New ticket created',
  message: 'Ticket ABC has been created',
  priority: 'medium',
  metadata: { ticketId: 'ABC' }
});

Marking as read from the UI​

The modal marks an item as read on click; use the “Mark all read” button for bulk.

🎉 Summary​

The notification system provides:

✅ Simplified, fast modal with real data ✅ RBAC on endpoints (owner/admin) ✅ In-app notifications for BO events; email for collaborator invites/resets ✅ Safe server-side helpers and fallbacks

The system is now ready for production use and provides a solid foundation for all notification needs in the Toto backoffice platform.