Production-ready, event-driven WhatsApp notification service built with TypeScript, Node.js, and AWS

• Event-Driven Architecture - Scalable SQS-based message processing
• Type-Safe - Full TypeScript with strict mode
• Automatic Retries - Exponential backoff for failed messages
• Scheduled Delivery - Send messages at specific times
• Analytics - Built-in delivery statistics and reporting
• Secure - API key authentication and rate limiting
• Monitored - Sentry error tracking and CloudWatch logging
• Containerized - Docker-ready for easy deployment

• Node.js 20+
• PostgreSQL 14+
• Redis 7+
• Docker (optional)

# Clone repository
git clone https://github.com/yourusername/whatsapp-notification-service.git
cd whatsapp-notification-service

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your credentials

# Generate Prisma client
npm run prisma:generate

# Run database migrations
npm run prisma:migrate dev

# Start services
npm run dev:api      # API server (port 3000)
npm run dev:worker   # Worker process

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

┌─────────┐      ┌─────────┐      ┌─────────┐      ┌──────────┐
│ Client  │─────▶│   API   │─────▶│   SQS   │─────▶│  Worker  │
└─────────┘      └────┬────┘      └─────────┘      └────┬─────┘
                      │                                  │
                      ▼                                  ▼
                 ┌─────────┐                      ┌──────────┐
                 │Database │                      │ WhatsApp │
                 │(Prisma) │                      │   API    │
                 └─────────┘                      └────┬─────┘
                      ▲                                │
                      │                                │
                      └────────────────────────────────┘
                              (Webhook Updates)

• API Service - REST API for notification ingestion
• Worker Service - SQS consumer for message processing
• Database - PostgreSQL for state management
• Redis - Caching and rate limiting
• SQS - Message queue for async processing

Create Notification:

curl -X POST http://localhost:3000/v1/notifications \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "order.placed",
    "recipient": {"phone_number": "+14155552671"},
    "template": {
      "name": "order_confirmation",
      "language": "en",
      "components": [...]
    }
  }'

Response:

{
  "success": true,
  "data": {
    "id": "notif_abc123",
    "status": "queued"
  }
}

• POST /v1/notifications - Create notification
• POST /v1/notifications/bulk - Bulk create
• GET /v1/notifications/:id/status - Get status
• GET /v1/analytics/stats - Delivery statistics
• GET /v1/analytics/notifications - List notifications
• GET /v1/health - Health check

Complete API Documentation: See docs/api.md for:

• Authentication details
• Full endpoint reference
• Request/response schemas
• Error codes
• Rate limiting
• Webhook integration
• SDK examples (Node.js, Python)

Configuration: See .env.example for complete environment variable reference.

whatsapp-notification-service/
├── packages/
│   ├── api/              # REST API service
│   ├── worker/           # SQS worker service
│   └── shared/           # Shared types and utilities
├── infrastructure/
│   └── database/         # Database schema
├── docs/                 # Documentation
├── prisma/               # Prisma schema and migrations
└── docker-compose.yml    # Docker configuration

# Development
npm run dev:api          # Start API in dev mode
npm run dev:worker       # Start worker in dev mode

# Building
npm run build            # Build all packages
npm run build:api        # Build API only
npm run build:worker     # Build worker only

# Testing
npm test                 # Run all tests
npm run test:watch       # Run tests in watch mode
npm run test:coverage    # Generate coverage report

# Database
npm run prisma:generate  # Generate Prisma client
npm run prisma:migrate   # Run migrations
npm run prisma:studio    # Open Prisma Studio

# Code Quality
npm run lint             # Run ESLint
npm run lint:fix         # Fix linting issues
npm run format           # Format code with Prettier

# Build and run
docker-compose up -d

# Scale services
docker-compose up -d --scale worker=3

# Deploy to production
./scripts/deploy.sh production

Deployment Guide: See docs/deployment.md for:

• Docker deployment
• AWS ECS setup
• Database migrations
• Scaling strategies
• Backup and recovery

Error tracking and performance monitoring automatically enabled in production.

Logs stream to:

• /whatsapp-notif/api - API logs
• /whatsapp-notif/worker - Worker logs

• Message delivery rate
• Success/failure rates
• Processing latency
• Queue depth

Monitoring Setup: See docs/monitoring.md for:

• Sentry configuration
• CloudWatch setup
• Metrics and dashboards
• Alert configuration

# Run all tests
npm test

# Unit tests only
npm test -- --testPathPattern=unit

# Integration tests
npm test -- --testPathPattern=integration

# Coverage report
npm run test:coverage

Coverage: 70%+ (target: 85%)

Testing Guide: See docs/testing.md for:

• Test structure and organization
• Writing unit and integration tests
• Mocking strategies
• Coverage goals

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Throughput: 5,000+ messages/minute
• Latency: p95 < 200ms (API), p95 < 5s (delivery)
• Availability: 99.9% uptime
• Success Rate: 99%+ delivery success

• API key authentication
• Rate limiting (per tenant and recipient)
• Input validation with Zod
• SQL injection protection (Prisma)
• Secrets management (AWS Secrets Manager)
• Regular security audits

Security Policy →

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

• Architecture - System design, components, and data flow
• Deployment - Docker and AWS deployment procedures
• Monitoring - Sentry and CloudWatch setup
• Testing - Testing strategy and guidelines
• Operations Runbook - Incident response and maintenance

• Contributing - How to contribute to this project
• Environment Setup - Configuration reference

• Documentation
• Issue Tracker
• Discussions

• WhatsApp Business API
• Fastify
• Prisma
• AWS SDK

Built by Your Name