Description

Overview

The Notifications module provides a comprehensive real-time notification system for the CoreBanq platform. It supports multi-channel delivery, user preference management, and async processing through queue integration. The system enables real-time communication with users through various channels including email, SMS, and browser notifications.

Core Features

🔔 Real-Time Notifications

Server-Sent Events (SSE): Real-time browser notifications
WebSocket-like Experience: Persistent connections for instant delivery
Multi-User Support: Broadcast notifications to multiple users
Connection Management: Automatic client registration and cleanup

📡 Multi-Channel Delivery

System Notifications: In-app notifications via SSE
Email Integration: HTML/text email notifications
SMS Integration: Text message notifications
Extensible Architecture: Easy addition of new channels (WhatsApp, Telegram, etc.)

⚙️ User Preference Management

Granular Control: Per-user, per-customer notification preferences
Channel Selection: Users can choose which channels to receive notifications on
Event-Based Configuration: Enable/disable specific notification events
Group Management: Notifications organized by type (chat, task, etc.)

🔄 Queue-Based Processing

Async Processing: Non-blocking notification delivery
Message Queuing: Reliable delivery with queue persistence
Batch Processing: Efficient handling of multiple notifications
Error Recovery: Retry mechanisms for failed deliveries

🗃️ Complete State Management

Notification Storage: Persistent storage of all notifications
Read/Unread Tracking: Individual read state per user
Delivery Confirmation: Track delivery status across channels
Historical Data: Complete notification history and analytics

API Endpoints

Get User Notifications

GET /v1/notifications

Retrieve all notifications for the authenticated user.

Query Parameters

limit (optional): Maximum number of notifications to return (default: 50)
offset (optional): Number of notifications to skip (default: 0)
status (optional): Filter by read/unread status (read, unread, all)
customer_id (optional): UUID of a customer to filter notifications for a specific customer context. If omitted, notifications for all customers linked to the authenticated user are returned.

Response

Get Single Notification

GET /v1/notifications/{notification_id}

Retrieve a specific notification by ID.

Response

Mark Notification as Read

PATCH /v1/notifications/{notification_id}/read

Mark a specific notification as read using partial update. This endpoint accepts partial fields and can be used as a generic update endpoint for any notification fields.

Request Body (Optional)

{
  "read": true
}

Note: If no request body is provided, the notification will be marked as read by default.

Response

Delete Notification

DELETE /v1/notifications/{notification_id}

Delete a specific notification for the authenticated user.

Response

Get User Preferences

GET /v1/notifications/preferences

Get the current notification preferences for the authenticated user.

Response

Update User Preferences

PUT /v1/notifications/preferences

Update notification preferences for the authenticated user.

Request Body

Real-Time Connection (SSE)

GET /v1/notifications/sse

Establish a Server-Sent Events connection for real-time notifications.

Authentication: Bearer token required

Headers

Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
Authorization: Bearer

Connection Management

Persistent Connections: SSE connections remain open until the client disconnects
No Server Timeout: WriteTimeout is disabled for SSE endpoints to support long-lived connections
Automatic Cleanup: Server automatically cleans up disconnected clients
Multi-User Support: Each user can have multiple concurrent SSE connections
Cross-Origin Support: CORS headers are automatically set for browser compatibility

Event Stream Format

data: {"id":"123e4567-e89b-12d3-a456-426614174000","type":"chat","event":"message_received","title":"New Message","content":"Hello from John","link_url":"/chat/room/456","link_text":"View Message","read":false,"created_at":"2024-01-15T10:30:00Z"}

Connection Lifecycle

Connect: Client establishes SSE connection with authentication
Register: Server registers client for the authenticated user
Receive: Client receives real-time notifications as they occur
Disconnect: Client closes connection or navigates away
Cleanup: Server automatically removes client from active connections

Test Notification Endpoints

Trigger Test Notification (Queue-based)

POST /v1/notifications/trigger

Development/Testing Only - Trigger a test notification through the full notification system (queue-based processing).

Authentication: API Key required

Request Body

{
  "type": "chats",
  "event": "message_received",
  "title": "Test Notification",
  "content": "This is a test notification",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_ids": ["123e4567-e89b-12d3-a456-426614174000"],
  "rec_type": "chats",
  "rec_id": "789e4567-e89b-12d3-a456-426614174000"
}

Response

{
  "message": "Notification sent to all connected users"
}

Send Direct SSE Notification

POST /v1/notifications/sse

Development/Testing Only - Send a notification directly to SSE clients (bypasses queue processing).

Authentication: API Key required

Request Body

Same as trigger endpoint above.

Response

{
  "message": "Notification sent to all connected users"
}

Error Codes

Code	Description
notifications_m.invalid_user_id	Invalid or missing authenticated user ID
notifications_m.invalid_id	Invalid notification ID
notifications_m.not_found	Notification not found
notifications_m.failed_to_mark_as_read	Failed to mark notification as read
notifications_m.failed_to_delete	Failed to delete notification
notifications_m.invalid_group	Invalid notification group
notifications_m.invalid_channel	Invalid notification channel
notifications_m.invalid_event	Invalid notification event
notifications_m.failed_to_fetch_notifications	Failed to fetch notifications
notifications_m.failed_to_fetch_preferences	Failed to fetch notification preferences
notifications_m.failed_to_update_preferences	Failed to update notification preferences

Best Practices

Performance Guidelines

Connection Limits: Implement per-user SSE connection limits
Message Batching: Process notifications in batches for efficiency
Queue Management: Monitor queue depths and processing rates
Database Optimization: Use appropriate indexes for notification queries

Security Guidelines

Authentication: Always verify user identity for notification access
Data Sanitization: Sanitize notification content before delivery
Audit Logging: Log all notification operations for security auditing
Rate Limiting: Implement rate limits for notification creation

User Experience Guidelines

Graceful Degradation: Handle SSE connection failures gracefully
Progressive Enhancement: Provide fallback for users without SSE support
Clear Messaging: Use clear, actionable notification content
Preference Respect: Always honor user notification preferences

Dependencies

Required Services

Database: PostgreSQL for notification storage
Queue: Message queue system (local or AWS SQS)
Storage: CoreBanq storage abstraction
RBAC: Role-based access control system

External Integrations

Email Service: For email notifications
SMS Service: For text message notifications
Authentication: User authentication and authorization

Configuration Dependencies

notifications.yaml: Notification configuration
queue.yaml: Queue system configuration
Database migration scripts for notification tables

The Notifications module provides a robust, scalable foundation for real-time user communication in the CoreBanq platform, with comprehensive features for multi-channel delivery, user preference management, and reliable message processing.

Description

On this page