Notification System
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Notification System is a core service within the jahid19978 project designed to handle multi-channel communication with users. It serves as a centralized hub for dispatching alerts, transactional messages, and system updates through various delivery providers including Email and SMS.
The system is architected to decouple message generation from delivery logic, allowing for high scalability and easy integration of new communication channels. It ensures that system events are communicated to owners and users reliably.
Sources: README.md:1-2, src/notifications/manager.py
System Architecture
The architecture follows a provider-based pattern where a central manager orchestrates the flow of data between the application triggers and the delivery services.
Components Overview
| Component | Description |
|---|---|
| Notification Manager | The primary entry point for sending notifications. Handles routing and provider selection. |
| Delivery Providers | Implementation-specific classes for third-party services (e.g., SMTP, Twilio). |
| Notification Model | Data structure representing the state and content of a notification. |
| Configuration | Externalized settings for API keys, endpoints, and retry logic. |
Sources: src/notifications/manager.py, src/notifications/models.py, config/notifications.yaml
Message Dispatch Flow
The following diagram illustrates the sequence of operations when the system receives a request to send a notification.
The sequence shows the synchronous flow from the application trigger to the provider dispatch, including persistence of the notification state.
Sources: src/notifications/manager.py, src/notifications/models.py
Implementation Details
Notification Manager
The NotificationManager class is responsible for loading configurations and initializing the requested providers. It utilizes a registry to map channel names to their respective implementation classes.
Key logic includes:
- Provider Resolution: Determining which service to use based on the
channelattribute in the request. - Error Handling: Catching provider-specific exceptions and logging them to the system state.
Sources: src/notifications/manager.py
Delivery Providers
The system currently supports two primary delivery channels. Each provider implements a standard interface to ensure consistency.
- Email Provider: Utilizes SMTP settings defined in the configuration to send HTML and text-based messages.
- SMS Provider: Connects to external gateways to deliver short messages to mobile devices.
This flowchart describes the internal routing logic used to select the appropriate delivery mechanism.
Sources: src/notifications/providers/email.py, src/notifications/providers/sms.py
Data Models and Configuration
Notification State Model
The system tracks every message through a structured data model to provide audit trails and retry capabilities.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the notification entry. |
recipient | String | Destination address (Email or Phone Number). |
content | Text | The actual body of the message. |
status | Enum | Current state: PENDING, SENT, FAILED. |
created_at | Timestamp | Time the request was initiated. |
Sources: src/notifications/models.py
Configuration Schema
Configuration is managed via a YAML file, allowing for environment-specific overrides without code changes.
notifications:
email:
host: "smtp.example.com"
port: 587
use_tls: true
sms:
provider_url: "https://api.sms-gateway.com"
retry_limit: 3
Sources: config/notifications.yaml
Conclusion
The Notification System provides a robust framework for managing communications within the jahid19978 project. By abstracting the delivery details into providers and maintaining a centralized manager, the system ensures that notifications are handled consistently and are easily auditable through the persistent data models.