Notification Service

1. Project Overview

A scalable, event-driven Notification Service built with ASP.NET Core.

The system supports:

• Topic-based notifications (delivered to subscribed users)
• Single-user notifications
• Multi-channel delivery
• User preferences
• Reliable message processing using RabbitMQ and Redis (cache-aside pattern)

---

2. Purpose

This project demonstrates how to design and implement a production-ready notification system using Clean Architecture principles.

It focuses on:

• Reliability
• Scalability
• Extensibility
• High availability

---

3. Key Features

• JWT Authentication & Role-Based Authorization
• Admin Notification Management (filtering, sorting, scheduling)
• User Inbox with read/unread tracking
• External API Integration (API key secured)
• Topic-Based Subscriptions (or single-user delivery)
• User Channel & Category Preferences
• Multi-Channel Delivery (Email & In-App)
• RabbitMQ-based asynchronous processing
• Retry Mechanism & Dead-Letter Queue support
• Real-time delivery ready (SignalR integration ready)
• Redis caching with cache-aside pattern
  • Caches topic subscribers
  • Caches categories
  • Caches user preferences
  • Falls back to database when cache is unavailable
• Clean Architecture with Domain Events

---

4. Functional Requirements

4.1 Multi-Channel Support

The system must support sending notifications through:

• Email
• SMS
• Push notifications
• In-app messages

---

4.2 Notification Delivery Modes

• Topic-based notifications (delivered to all subscribed users)
• Single-user notifications (direct messages)
• Scheduled notifications

---

4.3 Scheduled Delivery

The system must allow notifications to be scheduled for future delivery.

---

4.4 Rate Limiting

The system must ensure that users receive only a limited number of promotional notifications within a defined period to prevent spam.

---

4.5 Retry Mechanism

The system must handle notification delivery failures and retry when necessary.

---

5. Non-Functional Requirements

5.1 Scalability

The system should handle millions of notifications per minute and support millions of concurrent users.

---

5.2 High Availability

The system must ensure minimal downtime and continue delivering notifications during partial failures.

---

5.3 Reliability

The system must guarantee at-least-once delivery, with support for exactly-once semantics where applicable.

---

6. High-Level Design (HLD)

The system follows an event-driven, decoupled architecture where external services publish notifications via API (secured by API Key).

Notifications are processed through domain events and background jobs, then dispatched to RabbitMQ for asynchronous delivery.

Channel-specific consumers (Email, In-App/SignalR) process messages and update delivery status.

Redis is used for caching (cache-aside pattern) and database as source of truth.

Dead-letter queues and retry mechanisms ensure reliability and fault tolerance.

---

7. Notification Processing Flow Diagram

---

8. ERD (Entity Relationship Diagram)

---

9. Tech Stack

• ASP.NET Core
• RabbitMQ
• Redis (Cache-Aside Pattern)
• SQL Server / EF Core
• SignalR
• Clean Architecture

---

10. Requirements & Setup

Requirements

Make sure the following tools are installed:

• .NET 8 SDK
• SQL Server
• Docker Desktop
• Git
• Postman (optional)

---

1. Clone the Repository

git clone https://github.com/your-username/notification-service.git
cd notification-service

---

2. Start Infrastructure Services (Docker)

Redis

docker run -d \
  --name notification-redis \
  -p 6380:6379 \
  redis

Redis is used for cache-aside pattern implementation.

---

RabbitMQ (with Management UI)

docker run -d \
  --name notification-rabbitmq \
  -p 5672:5672 \
  -p 15672:15672 \
  rabbitmq:3-management

RabbitMQ Management UI:

http://localhost:15672

Default credentials:

Username: guest
Password: guest

---

RabbitMQ Configuration (appsettings.json)

"RabbitMq": {
  "Connection": {
    "HostName": "localhost",
    "Port": 5672,
    "UserName": "guest",
    "Password": "guest"
  },

  "Topology": {
    "MainExchange": "notifications.dispatch",
    "DeadLetterExchange": "notifications.dlx",

    "EmailQueue": "notifications-email",
    "InAppQueue": "notifications-inapp",
    "PushQueue": "notifications-push",
    "SmsQueue": "notifications-sms",

    "EmailRoutingKey": "channel.email",
    "InAppRoutingKey": "channel.inapp",
    "PushRoutingKey": "channel.push",
    "SmsRoutingKey": "channel.sms"
  }
}

---

3. Configure Database

Update the connection string in:

src/Project.Api/appsettings.json

Example:

"ConnectionStrings": {
  "DefaultConnection": "Server=.;Database=NotificationServiceDb;Integrated Security=true;TrustServerCertificate=True;"
}

---

4. Apply Database Migrations

Make sure you are in the solution root directory, then run:

dotnet ef database update --project src/Project.Infrastructure --startup-project src/Project.Api

If EF tools are not installed:

dotnet tool install --global dotnet-ef

---

5. Configure Mailtrap (Email Testing)

This project uses Mailtrap for development email testing.

Update SmtpOptions in appsettings.json:

"SmtpOptions": {
  "Host": "sandbox.smtp.mailtrap.io",
  "Port": 587,
  "EnableSsl": true,
  "Username": "<your-username>",
  "Password": "<your-password>"
}

Steps:

1. Create a Mailtrap account
2. Create a sandbox inbox
3. Replace credentials in appsettings.json

---

6. Configure JWT

Update JWT settings in appsettings.json:

"JwtOptions": {
  "Issuer": "https://localhost:7030",
  "Audience": "Audience",
  "SecretKey": "<your-secret-key>",
  "ExpirationInHours": "1"
}

⚠️ Do NOT commit real secret keys to public repositories.

Use environment variables or .NET User Secrets instead.

---

11. Running the Application

Restore dependencies:

dotnet restore

Build the solution:

dotnet build

Run the API:

dotnet run --project src/Project.Api

The API will be available at:

https://localhost:7030

Swagger UI:

https://localhost:7030/swagger

---

12. API Documentation

Swagger UI

Available at:

https://localhost:xxxx/swagger

---

OpenAPI Specification

The OpenAPI JSON file is available in:

docs/openapi.json

---

Postman Collection

Import the collection from:

docs/notification-service.postman_collection.json

---

13. Optional: Run with Docker

docker-compose up --build

---

14. Future Improvements

• SMS Integration
• Push Notifications
• Kubernetes Deployment
• Observability (Prometheus & Grafana)
• Distributed Tracing

---

License

This project is licensed under the MIT License — see the LICENSE file for details.