Notification Management System
Relevant source files
The following files were used as context for generating this wiki page:
The Notification Management System in BankChase is a production-ready, multi-channel alerting engine designed to provide real-time updates for all financial events. The system supports three primary communication channels: Email (via Resend), SMS (via Termii), and In-App Push notifications. Its core architecture is built for non-blocking asynchronous execution, ensuring that notification delivery does not impede the speed of core banking transactions or webhook processing.
The scope of the system includes automated triggers for money movement (credits, debits, deposits), transfer failure alerts, and security-related messaging such as One-Time Passwords (OTP) for Two-Factor Authentication. The system is deeply integrated with the Paystack webhook infrastructure to automatically react to external transaction status changes.
Sources: NOTIFICATION_SYSTEM_SUMMARY.md:3-8, NOTIFICATIONS_IMPLEMENTATION_SUMMARY.md:6-15
System Architecture and Multi-Channel Engine
The engine is designed to handle multiple delivery channels simultaneously. It uses a fire-and-forget approach where notifications are dispatched in the background after the primary transaction or webhook logic has completed, often returning an HTTP 200 response immediately while processing the alerts asynchronously.
Core Delivery Channels
| Channel | Provider | Purpose |
|---|---|---|
| Resend | Rich HTML templates for credit/debit alerts and failed transfers. | |
| SMS | Termii | 160-character optimized alerts and OTP delivery for 2FA. |
| Push | In-App (DB) | Real-time notifications with mark-as-read and history tracking. |
Sources: NOTIFICATION_SYSTEM_SUMMARY.md:16-29, NOTIFICATIONS_IMPLEMENTATION_SUMMARY.md:18-24
Notification Delivery Flow
The following diagram illustrates how a transaction event (such as a Paystack webhook) triggers the multi-channel engine.
Data Models and Schemas
The system persists notification history and user preferences within a hybrid database structure. In-app notifications are stored in a dedicated table to allow for pagination and status management (read/unread).
Notifications Table Schema
The system uses a notifications table to track the delivery and read status of in-app alerts.
| Field | Type | Description |
|---|---|---|
id | UUID | Primary key for the notification. |
user_id | UUID | Foreign key to the user receiving the alert. |
type | TEXT | Type of alert (credit, debit, transfer_failed, deposit, system). |
title | TEXT | Concise summary (e.g., "Money Received"). |
message | TEXT | Detailed notification content. |
read | BOOLEAN | Indicates if the user has viewed the notification (defaults to false). |
action_url | TEXT | Deep link for the user to navigate to the transaction details. |
Sources: NOTIFICATION_SYSTEM_SUMMARY.md:144-162, NOTIFICATION_SETUP_GUIDE.md:120-136
Notification Preferences
User profiles are extended to include granular controls over which channels they wish to receive alerts on. This is typically stored as a JSONB object containing boolean flags for email, sms, and push.
Sources: NOTIFICATION_SYSTEM_SUMMARY.md:169-178, NOTIFICATION_SETUP_GUIDE.md:146-151
Integration and Automated Triggers
Notifications are automatically triggered by specific banking events identified through API calls or external webhooks.
Automated Event Triggers
The system monitors four primary money movement events:
- Credit Alert: Triggered when a user receives money via bank transfer, P2P, or deposit.
- Debit Alert: Triggered when a user successfully sends money.
- Transfer Failed: Triggered when a transfer fails, typically including refund information.
- Deposit: Triggered when money is received specifically into a virtual account.
Sources: NOTIFICATION_SYSTEM_SUMMARY.md:33-47, NOTIFICATIONS_IMPLEMENTATION_SUMMARY.md:27-35
Sequence Diagram: Transfer Success Notification
The sequence below shows the interaction between the system components during a successful transfer.
Configuration and API Reference
The system relies on specific environment variables for API authentication with third-party providers.
Environment Variables
| Variable | Required | Description |
|---|---|---|
RESEND_API_KEY | Yes | API key from resend.com for email delivery. |
TERMII_API_KEY | Yes | API key from termii.com for SMS delivery. |
SENDER_EMAIL | Yes | Verified email address used as the "From" address. |
SMS_SENDER_ID | Yes | Approved alphanumeric ID for SMS (e.g., "BankChase"). |
PAYSTACK_SECRET_KEY | Yes | Used to verify HMAC signatures for incoming webhooks. |
Sources: NOTIFICATIONS_QUICK_START.md:13-18, NOTIFICATION_SYSTEM_SUMMARY.md:132-140
Key API Endpoints
The following endpoints facilitate notification management for the client applications:
- GET
/api/notifications: Retrieves a paginated list of notifications for the authenticated user. - PUT
/api/notifications/[id]/read: Marks a specific notification as read. - DELETE
/api/notifications/[id]: Removes a notification from the user's history. - POST
/api/notifications/test-email: Utility endpoint for developers to verify Resend configuration.
Sources: NOTIFICATION_SYSTEM_SUMMARY.md:88-99, NOTIFICATION_SETUP_GUIDE.md:225-235
Conclusion
The Notification Management System serves as a vital communication layer for BankChase, providing security and transparency to users regarding their financial activities. By utilizing professional providers like Resend and Termii and implementing an asynchronous architecture, the system maintains high reliability and performance, ensuring that users are alerted to transaction statuses within seconds without affecting the core banking operations.
Sources: NOTIFICATION_SYSTEM_SUMMARY.md:235-245, NOTIFICATIONS_IMPLEMENTATION_SUMMARY.md:166-180