Service Design Specification

Notification Service Documentation Version: 1.0

Scope

This document provides a comprehensive architectural overview of the Notification Service, which is responsible for sending multi-channel notifications via Email, SMS, and Push. The service supports both REST and gRPC interfaces and utilizes an event-driven architecture through Kafka.

This document is intended for:

• Backend Developers integrating notification capabilities.
• DevOps Engineers deploying or monitoring the notification system.
• Architects evaluating extensibility, observability, and scalability.

For detailed REST interface, refer to the [REST API Guide]. For Kafka-based publishing and consumption flows, refer to the [Event API Guide].

Service Settings

• Port: Configurable via HTTP_PORT, default: 3000

• Primary Interfaces:

  • REST over Express
  • gRPC over Proto3
  • Kafka via event topics

• Database: PostgreSQL (via Sequelize)

• Optional: Redis (for caching or state sharing)

• Email/SMS/Push Provider Configuration: Dynamically switchable via .env

Interfaces Overview

REST API

Exposes endpoints to:

• Register/unregister devices
• Fetch user notifications
• Send new notifications
• Mark notifications as seen

For full list and parameters, refer to the REST API Guide.

gRPC API

Defined via notification.sender.proto:

• SendNotice() RPC triggers notification dispatch for all specified channels.
• Used for inter-service communication where synchronous flow is preferred.

Kafka Events

• The service publishes to and subscribes from:

  • <codename>-notification-email
  • <codename>-notification-push
  • <codename>-notification-sms

For event structure and consumption logic, refer to the Event API Guide.

Provider Architecture

Each channel (SMS, Email, Push) is pluggable using a provider pattern. Providers can be toggled via env vars.

Email Providers

• SendGrid
• SMTP
• AmazonSES
• FakeProvider (for dev/test)

Push Providers

• Firebase (FCM)
• OneSignal
• AmazonSNS
• FakeProvider

SMS Providers

• Twilio
• AmazonSNS
• NetGSM
• Vonage
• FakeProvider

Each provider implements a common send(payload) method and logs delivery result.

Storage Mode

Notifications can be optionally stored in the PostgreSQL database if STORED_NOTICE=true and notificationBody.isStored=true.

Stored data includes:

• userId, title, body
• metadata (JSON)
• isSeen flag
• createdAt / updatedAt timestamps

Aggregation & Templating

Notification body and title can be:

• Directly passed as raw strings

• Or dynamically populated via predefined templates:

  • WELCOME
  • OTP
  • RESETPASSWORD
  • NONE (no template)

Template rendering supports interpolation with metadata. Separate template files exist for:

• Email (HTML)
• SMS (Text)
• Push (structured JSON)

Middleware

Error Handling

• ApiError used for standard error shaping
• errorConverter, errorHandler used globally

Validation

• All routes use Joi schema validation

• Validations available for:

  • Device registration
  • Notification send
  • Pagination and sort filters
  • Mark-as-seen by IDs

Utilities

• pick(): Selects allowed keys from request
• pagination(): Sequelize-based paginated query utility

Lifecycle & Boot Process

1. Loads configuration from .env using dotenv

2. Initializes:

   • Express HTTP Server
   • gRPC Server (if GRPC_ACTIVE=true)
   • Kafka listeners
   • Redis connection
   • PostgreSQL connection

3. Injects OpenAPI/Swagger via api-face

4. Registers REST routes and middleware

5. Launches any scheduled cron jobs

6. Handles graceful shutdown via SIGINT

Environment Variables

Testing Strategy

Unit Tests

• Provider .send() methods
• Templating with metadata
• Validation schema boundaries

Integration Tests

• REST endpoint workflows
• Kafka → Listener execution
• gRPC request handling

End-to-End (Optional)

• Simulate a full pipeline: Send → Store → Fetch → Mark as Seen

Observability & Logging

• Each send call logs payload & result to console
• Provider-specific errors include stack traces