Notification Gateway

A lightweight notification routing service that accepts notification requests via a REST API and dispatches them to the appropriate delivery channel: email (Amazon SES), SMS (Amazon SNS), or push notifications (Amazon SNS Platform Applications). All delivery attempts are logged to Amazon DynamoDB.

Architecture

Upstream systems send notification requests to the gateway via a single REST endpoint (POST /notify). The gateway validates the request, routes it to the appropriate delivery channel based on the channel field (email via Amazon SES, SMS via Amazon SNS, or push via Amazon SNS Platform Applications), and logs the delivery outcome (success or failure) to an Amazon DynamoDB table.

Tech Stack

• Runtime: Node.js 20+
• Framework: Express 4
• Cloud Services: Amazon SES, Amazon SNS, Amazon DynamoDB
• Config: dotenv

Project Structure

notification-gateway/
├── src/
│   ├── index.js          # Express app entry point
│   ├── config.js         # Environment configuration
│   ├── logger.js         # DynamoDB delivery logging
│   ├── routes/
│   │   └── notify.js     # POST /notify route handler
│   └── channels/
│       ├── ses.js        # Email via Amazon SES
│       ├── sns-sms.js    # SMS via Amazon SNS
│       └── sns-push.js   # Push via Amazon SNS Platform Apps
├── test/
│   └── notify.test.js    # Basic validation tests
├── .env.example
├── package.json
└── README.md

Setup

1. Clone the repository:

   git clone https://github.com/your-org/notification-gateway.git
   cd notification-gateway

2. Install dependencies:

   npm install

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your AWS credentials and resource ARNs

4. Ensure AWS credentials are available (via environment, IAM role, or ~/.aws/credentials).

5. Create the DynamoDB table:

   aws dynamodb create-table \
     --table-name notification-delivery-log \
     --attribute-definitions AttributeName=id,AttributeType=S \
     --key-schema AttributeName=id,KeyType=HASH \
     --billing-mode PAY_PER_REQUEST

6. Start the server:

   npm start

API

POST /notify

Send a notification through a specified channel.

Request body:

{
  "channel": "email",
  "recipient": "user@example.com",
  "subject": "Welcome",
  "body": "Thanks for signing up!"
}

Field	Type	Required	Description
channel	string	yes	One of: email, sms, push
recipient	string	yes	Email address, phone number (E.164), or device token
subject	string	no	Subject line (used by email and push)
body	string	yes	Message content

Success response (200):

{
  "status": "sent",
  "messageId": "abc123"
}

Error response (400):

{
  "error": "Missing required fields: channel, recipient, body"
}

Error response (502):

{
  "status": "failed",
  "error": "SES sending quota exceeded"
}

GET /health

Health check endpoint.

Response (200):

{
  "status": "ok"
}

Running Tests

npm test