🚀 Scalable Notification System

A production-style Notification System built using Node.js, TypeScript, PostgreSQL, Redis, BullMQ, and Docker.

This project demonstrates modern backend engineering concepts including:

• Asynchronous job processing
• Queue-based architecture
• Worker systems
• Multi-channel notifications
• Dead Letter Queue (DLQ)
• Scheduling
• Retry mechanisms
• Idempotency handling
• Distributed system patterns

---

🧠 Architecture Overview

Flow

1. API receives notification request
2. Notification stored in PostgresSQL
3. Job pushed to Redis queue
4. Worker Processes job asynchronously
5. Notification delivered via Email/SMS/Push
6. Status updated in database

---

✨ Features

• ✅ BullMQ-based async job processing
• ✅ Redis-backed queue system
• ✅ Worker architecture
• ✅ Multi-channel notifications Email SMS Push
• ✅ Dead Letter Queue (DLQ)
• ✅ Retry handling with exponential backoff
• ✅ Delayed/scheduled notifications
• ✅ Idempotency support
• ✅ Structured logging
• ✅ Layered backend architecture
• ✅ Dockerized setup
• ✅ PostgreSQL persistence

---

🛠️ Tech Stack

• Backend: Node.js, TypeScript, Express
• Database: PostgreSQL
• Queue: Redis + BullMQ
• Tooling: tsx, nodemon
• DevOps Docker, Docker compose

---

📂 Project Structure

src/
├── config/         # DB, Redis, logger, env configs
├── controllers/    # HTTP request handlers
├── dto/            # Request DTOs
├── middlewares/    # Error handling & rate limiting
├── providers/      # Email/SMS/Push providers
├── queues/         # BullMQ queues
├── repository/     # Database queries
├── routes/         # API routes
├── service/        # Business logic
├── types/          # TypeScript types
├── workers/        # Background workers
└── server.ts       # Entry point

⚙️ Setup Instructions

1️⃣ Clone the repository

git clone <your-repo-url>
cd notification-system

2️⃣ Install dependencies

npm install

3️⃣ Setup environment variables

PORT=3000

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=yourpassword
DB_NAME=notification-system

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

EMAIL_USER=your_email
EMAIL_PASS=your_password

🚀 Running without docker

4️⃣ Start Redis (Docker)

docker run -d -p 6379:6379 redis

5️⃣ Start API server

npm run dev

6️⃣ Start Worker (separate terminal)

npx tsx src/workers/notification.worker.ts

🐳 Docker Setup

docker compose up --build

🧪 API Usage

Create Notification

POST /api/v1/notifications

{
  "user_id": "user_123",
  "type": "EMAIL",
  "message": "Hello from Notification system",
  "email": "user@email.com"
}

Headers:

idempotency_key: unique-key-123

🔁 Notification Lifecycle

PENDING
   ↓
PROCESSING
   ↓
SENT

OR

FAILED
   ↓
Dead Letter Queue

🧠 Key Concepts Implemented

• Queue-based architectures
• Producer-consumer pattern
• Distributed system patterns
• Background workers
• Async processing
• Retry systems
• Exponential backoff
• Dead Letter Queues
• Idempotency handling
• Multi-channel provider abstraction
• Delayed job scheduling
• Infrastructure containerization

---

💡 Learnings

This project helped in understanding:

• Distributed backend systems
• Async job orchestration
• Redis queue processing
• Worker-based architectures
• Backend scalability patterns
• Fault-tolerant systems
• Dockerized infrastructure

👨‍💻 Author

Kushal Chavan