ML-Powered Notification Delivery Optimization
Quick Start • Deploy • Docs • Architecture • Adopters • Contribute
Learns when each user is most likely to engage with notifications, then automatically schedules delivery at those times.
The Problem: Most apps send notifications at fixed times (9am, 6pm). Users ignore them because they arrive during meetings, sleep, or commutes.
This Solution:
- Tracks when users click notifications
- Trains an XGBoost model on this data (nightly)
- Predicts best send time per user (real-time)
- Schedules delivery accordingly
Pilot goal: Validate whether user-specific timing and attention-aware routing improve engagement, reduce fatigue, and lower risky sends compared with fixed-time delivery.
Production metrics note: This project has not yet been validated with production customer data. Engagement lift, accuracy, latency, throughput, ROI, cost, and reliability must be measured in each adopter's own AWS account before making production claims.
Core Components:
- Ingestion: React console/API clients → API Gateway + Cognito → Control Plane Lambda → Kinesis → S3 data lake + DynamoDB
- ML Pipeline: Glue (Spark) → SageMaker (XGBoost) → Endpoint
- Attention Escrow: Decision Lambda scores attention cost/value before scheduling
- Category Policies: Admin console/API manages organization-specific notification defaults that remain overrideable per send
- Template Library: Admin console/API stores reusable subject/body templates with variables like
{{name}},{{firstName}},{{email}}, and custom placeholders, then loads them into Campaigns, Send Event, and Attention Escrow workflows - Delivery: EventBridge Scheduler → Sender Lambda → Email (SES) / SMS (SNS)
- Feedback: SES configuration set → SNS bounce/complaint topics → SES Event Processor Lambda → suppression and audit tables
Built entirely on AWS serverless (Lambda, SageMaker, Glue, S3, DynamoDB).
Detailed Architecture • Deployment Guide • Cost Analysis • Limitations
git clone https://github.com/Yadab-Sd/smart-notification-routing-engine.git
cd smart-notification-routing-engine
./scripts/setup.shThis installs AWS CLI, Node.js, Java, Maven, CDK and configures everything.
# Set SENDER_EMAIL in infra/cdk/.env first
# Deploy infrastructure
./scripts/deploy-infra.sh
# Build, upload, and invalidate the frontend
./scripts/deploy-frontend.shTakes 10-15 minutes. Creates 8 CloudFormation stacks.
For GitHub-based frontend deployment, use the optional manual Frontend Deploy workflow after configuring AWS OIDC.
# Get API URL
API_URL=$(aws cloudformation describe-stacks --stack-name SR-Compute \
--query "Stacks[0].Outputs[?OutputKey=='ApiUrl'].OutputValue" --output text)
# Health check
curl $API_URL/v1/healthComplete Setup Guide • Deployment Guide
Predicts: Will user click notification sent at hour X?
Features (current):
- Hour of day (0-23)
- User's 7-day click rate
- Historical send volume per hour
Algorithm: XGBoost binary classifier (200 trees, depth 6)
Training: Nightly at 02:00 UTC on last 30 days of data
Inference: Iterate through next 24-48 hours, pick hour with highest predicted click probability.
# 1. Create user (required first)
POST /v1/users
# 2. Track events
POST /v1/events
# 3. Optional: create reusable notification categories
POST /v1/categories
# 4. Optional: create reusable message templates
POST /v1/templates
# 5. Get optimal send time
POST /v1/decisions/preview
# Response
{
"userId": "user_123",
"hour": 14,
"probability": 0.73,
"attentionDecision": "SEND",
"attentionCost": 2.4,
"attentionValue": 5.9,
"attentionReason": "Predicted value exceeds attention cost"
}User Management API • Multi-Channel Guide
Primary config: infra/cdk/.env
Important: Email must be verified in Amazon SES before deployment.
aws sesv2 create-email-identity --email-identity [email protected]Monthly AWS costs:
| Scale | Events/Day | Cost/Month |
|---|---|---|
| Small | 1M | $240 |
| Medium | 10M | $500 |
| Large | 50M | $1,665 |
Make code changes:
./scripts/build-services.sh
cd infra/cdk && pnpm exec cdk deploy SR-ComputeView logs:
aws logs tail /aws/lambda/SR-Compute-ControlPlaneFn --followDestroy everything:
cd infra/cdk && pnpm exec cdk destroy --allStart with the Documentation Index if you are new to the project.
- FEATURES.md - Complete list of all 18+ features (ML optimization, multi-channel, SES compliance, analytics, etc.)
- Complete Setup Guide
- Deployment Guide
- Local Development
- API Examples
- User Management API
- Multi-Channel Guide
- Architecture Deep Dive
- Architecture Decisions
- Channel Architecture (Strategy Pattern)
- Attention Escrow
- ML Pipeline
- API Reference
- Roadmap
- Cost Analysis
- Monitoring
- Operations Runbook
- Threat Model
- Known Limitations
- SES Production Access
- Compliance Guidance
- US Impact & Government Alignment
MIT License - see LICENSE for details.
Copyright (c) 2025 Yadab Sutradhar
Organizations can self-deploy this project in their own AWS account, modify it under the MIT license, and evaluate it with their own notification workflows.
If your organization evaluates or uses SNRE and finds it useful, feedback is welcome. A short note or letter describing the notification challenge, the SNRE capabilities reviewed, and any practical benefit to your workflow can help guide future open-source development. Email here [email protected]
See Feedback And Impact Notes. Please do not share sensitive data, private customer information, or confidential system details.
Help improve the system through issues, pull requests, tests, docs, integrations, and implementation feedback.
👉 CONTRIBUTING.md - Contributor guidelines
@software{yadab_sutradhar_2026_20707474,
author = {Yadab Sutradhar},
title = {Yadab-Sd/smart-notification-routing-engine: v2.6.0
- Template Library Release - 07/04/2026
},
month = jul,
year = 2026,
publisher = {Zenodo},
version = {v2.6.0},
doi = {10.5281/zenodo.20707474},
url = {https://doi.org/10.5281/zenodo.20707474},
}Built with ❤️ using AWS Serverless • XGBoost • Apache Spark
Last updated: July 2026