A high-performance, resilient notification microservice built with Node.js and TypeScript. Supporting multiple channels including Email (Resend), Push (Firebase), and SMS (Twilio), with built-in queuing and intelligent retry logic.
- Multi-channel Support:
- Email: Powered by Resend with react-email templates.
- Push: Managed via Firebase Cloud Messaging (FCM).
- SMS: Delivered through Twilio.
- Lightweight Persistence: Uses SQLite via
better-sqlite3for fast, intentional, and zero-configuration storage. - Resilient Delivery:
- Custom Queue System: Separate priority and normal queues for different channels.
- Exponential Backoff: Automatic retries (default 3x) with increasing delays.
- Rate Limiting: Built-in protection to stay within provider quotas.
- Runtime: Node.js
- Language: TypeScript
- Database: SQLite (
better-sqlite3) - Email: Resend, React-email
- SMS: Twilio
- Push: Firebase Admin SDK
- Web Framework: Express
This service supports two ways of sending emails:
Send standard HTML or plain text emails directly by providing the content in the payload.
Leverage react-email to send professionally designed, responsive emails.
-
Create the Template: Create a new
.tsxfile insrc/templates/email/(e.g.,MyNewTemplate.tsx). Use standardreact-emailcomponents.// src/templates/email/MyNewTemplate.tsx export const MyNewTemplate = ({ name }: { name: string }) => ( <Html> <Text>Hello {name}, this is a templated email!</Text> </Html> );
-
Register the Template: Open
src/services/emailTemplate.service.tsand add your template metadata to theregisterTemplatesmethod.this.templates.set('my-template-id', { id: 'my-template-id', name: 'My New Template', description: 'A description of what this email does', defaultSubject: 'Welcome to our platform!', requiredVariables: ['name'], });
-
Implement the Renderer: In the same file (
src/services/emailTemplate.service.ts), update therenderTemplatemethod'sswitchstatement handles your template.switch (templateId) { case 'my-template-id': component = React.createElement(MyNewTemplate, variables as any); break; // ... other cases }
- Node.js (v18+)
- Local SQLite installation (not strictly required as
better-sqlite3handles it)
-
Clone the repository:
git clone <repo-url> cd notification-ms
-
Install dependencies:
npm install
-
Configure Environment: Copy
.env.exampleto.envand fill in your credentials.cp .env.example .env
# Development mode with hot-reloading
npm run dev
# Build for production
npm run build
# Start production server
npm run startsrc/api: Route and Controller definitions.src/config: Environment and service configurations.src/controllers: Request handlers.src/lib: Core logic includingqueueManagerandrateLimiter.src/providers: External service integrations (Email, SMS, Push).src/services: Business logic (Notification, Email Templates, Scheduler).src/stores: Data access layer (SQLite).src/templates: React-email templates.
- Creation: A notification request is received and stored in SQLite with a
pendingstatus. - Queuing: The notification is added to the appropriate channel queue (Email/SMS/Push) based on priority.
- Processing: The
queueManagerpicks up the job and calls the respectiveprovider. - Failure & Retry: If a provider fails, the service calculates an exponential backoff delay and re-queues the notification (up to 3 times).
- Completion: Upon success or final failure, the status is updated in the database for tracking.
ISC License.