- Overview
- Architecture
- Project Structure
- Core Services
- Infrastructure
- Observability
- Getting Started
- Documentation
A highly scalable, distributed notification system built with microservices architecture. This system handles multi-channel notifications (email, push, SMS) with high throughput, reliability, and observability.
- 🚀 High Performance - Handles thousands of notifications per second
- 🔄 Multi-Channel Support - Email, Push notifications, and more
- 🛡️ Resilience - Built-in circuit breakers, retries, and idempotency
- 📊 Full Observability - Metrics, logs, and distributed tracing
- 🔌 Event-Driven - RabbitMQ-based message streaming
- 🐳 Container-Ready - Fully dockerized for easy deployment
This system follows a microservices architecture pattern with event-driven communication, leveraging RabbitMQ for reliable message streaming and Redis for caching and session management.
notification-system/
│
├── 🌐 api_gateway/ # API Gateway & routing layer
│
├── ⚙️ services/
│ ├── user_service/ # User management & authentication
│ ├── template_service/ # Notification template management
│ ├── email_service/ # Email notification handler
│ ├── push_service/ # Push notification handler
│
├── 🏢 infra/
│ ├── rabbitmq/ # Message broker configuration
│ ├── redis/ # Caching & session store
│ ├── postgres/ # Primary database
│ ├── nginx/ # Load balancer & reverse proxy
│
├── 🔧 shared/
│ └── libs/
│ ├── circuit_breaker/ # Circuit breaker pattern
│ ├── idempotency/ # Idempotency handling
│ ├── retry/ # Retry logic & backoff
│ └── logging/ # Centralized logging utilities
│
├── 📊 observability/
│ ├── prometheus/ # Metrics collection
│ ├── grafana/ # Metrics visualization
│ ├── loki/ # Log aggregation
│ ├── jaeger/ # Distributed tracing
│ └── alerting/ # Alert management
│
├── 🚀 deployments/
│ ├── docker/ # Docker compose configurations
│ ├── staging/ # Staging environment configs
│ └── production/ # Production environment configs
│
├── 🔄 .github/
│ └── workflows/ # CI/CD pipelines
│
└── 📚 docs/
├── architecture_diagram/ # System architecture diagrams
├── openapi_specs/ # API specifications
└── readmes/ # Additional documentation
| Service | Description | Port |
|---|---|---|
| API Gateway | Entry point for all client requests, handles routing and authentication | 8000 |
| User Service | Manages user accounts, preferences, and authentication | 8001 |
| Template Service | Handles notification templates and personalization | 8002 |
| Email Service | Processes and sends email notifications | 8003 |
| Push Service | Handles push notifications to mobile devices | 8004 |
- RabbitMQ - Reliable message broker for asynchronous communication
- PostgreSQL - Primary relational database
- Redis - High-performance caching and session management
- Nginx - Reverse proxy and load balancer
| Tool | Purpose |
|---|---|
| Prometheus | Metrics collection and alerting |
| Grafana | Metrics visualization and dashboards |
| Loki | Log aggregation and querying |
| Jaeger | Distributed request tracing |
- Request throughput and latency
- Service health and uptime
- Queue depths and processing rates
- Error rates and types
- Resource utilization (CPU, memory, disk)
- Docker & Docker Compose
- Node.js (v18+) or Python (v3.10+)
- RabbitMQ
- PostgreSQL
- Redis
# Clone the repository
git clone https://github.com/brainox/hng-group55-distributed-notification-system.git
cd hng-group55-distributed-notification-system
# Start infrastructure services
docker-compose -f deployments/docker/docker-compose.yml up -d
# Start individual services (example)
cd services/email_service
npm install && npm startEach service requires its own environment configuration. Copy the example env files:
cp .env.example .envUpdate the .env files with your specific configuration values.
Contributions are welcome! Please read our contributing guidelines before submitting pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.
HNG Group 55 - Building scalable notification systems
Made with ❤️ by HNG Group 55