{"id":30172890,"url":"https://github.com/alexnthnz/notification-system","last_synced_at":"2025-08-11T23:18:10.653Z","repository":{"id":307768653,"uuid":"1027548810","full_name":"alexnthnz/notification-system","owner":"alexnthnz","description":"A scalable, Go-based Notification Service inspired by Alex Xu's system design principles. Supports multi-channel notifications (email, SMS, push) with a microservices architecture, using Kafka/NATS for queuing, PostgreSQL/Redis for storage, and Prometheus/Grafana for monitoring.","archived":false,"fork":false,"pushed_at":"2025-08-02T03:39:35.000Z","size":52,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T06:25:00.628Z","etag":null,"topics":["go","grpc","kafka","notification","postgres","redis","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexnthnz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-28T07:15:38.000Z","updated_at":"2025-08-02T05:47:26.000Z","dependencies_parsed_at":"2025-08-02T08:00:30.231Z","dependency_job_id":null,"html_url":"https://github.com/alexnthnz/notification-system","commit_stats":null,"previous_names":["alexnthnz/notification-system"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/alexnthnz/notification-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexnthnz%2Fnotification-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexnthnz%2Fnotification-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexnthnz%2Fnotification-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexnthnz%2Fnotification-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexnthnz","download_url":"https://codeload.github.com/alexnthnz/notification-system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexnthnz%2Fnotification-system/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269970135,"owners_count":24505476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","grpc","kafka","notification","postgres","redis","rest-api"],"created_at":"2025-08-11T23:18:05.021Z","updated_at":"2025-08-11T23:18:10.652Z","avatar_url":"https://github.com/alexnthnz.png","language":"Go","readme":"# Notification Service (Go)\n\n## Overview\nThe Notification Service is a scalable, high-performance system built in Go to deliver notifications across multiple channels, such as email, SMS, and push notifications. Inspired by Alex Xu's system design principles, it emphasizes modularity, scalability, and fault tolerance.\n\n## Features\n\n- **Multi-Channel Support**: Sends notifications via email, SMS, and mobile push notifications.\n- **Scalability**: Handles high throughput using Go's concurrency model and distributed architecture.\n- **Reliability**: Ensures delivery with retry mechanisms and fault-tolerant design.\n- **Extensibility**: Easily integrates new notification channels or providers.\n- **Monitoring and Analytics**: Tracks delivery status and system metrics.\n- **Dual API Support**: Both REST and gRPC APIs for maximum flexibility.\n\n## Architecture\nThe system follows a microservices-based architecture with the following components:\n\n- **API Gateway**: Routes incoming HTTP/gRPC requests to the Notification Service.\n- **Notification Service**: Core service written in Go to process and queue notifications.\n- **Message Queue**: Uses Kafka for decoupling notification processing and delivery.\n- **Channel Services**: Go-based services for each channel (Email, SMS, Push).\n- **Database**: Stores notification metadata and user preferences.\n- **Monitoring Service**: Tracks system health and delivery metrics.\n\n## Data Flow\n\n1. Clients send notification requests to the API Gateway via REST or gRPC.\n2. The Notification Service validates requests, stores metadata, and publishes to a message queue.\n3. Channel Services consume queue messages and send notifications via third-party providers (e.g., SendGrid for email, Twilio for SMS, Firebase for push).\n4. Delivery status is updated in the database, and metrics are sent to the Monitoring Service.\n\n## Technologies Used\n\n- **Language**: Go (1.23+)\n- **APIs**: REST with Gorilla Mux + gRPC with Protocol Buffers\n- **Message Queue**: Apache Kafka\n- **Database**: PostgreSQL for metadata, Redis for caching\n- **Channel Services**: Go with HTTP clients for third-party API calls\n- **Monitoring**: Prometheus and Grafana\n- **Third-Party Providers**: SendGrid (Email), Twilio (SMS), Firebase (Push)\n\n## Project Structure\n```\nnotification-system/\n├── cmd/\n│   ├── api/               # Main API server (REST + gRPC)\n│   ├── email-service/     # Email channel service\n│   ├── sms-service/       # SMS channel service\n│   ├── push-service/      # Push notification service\n├── internal/\n│   ├── config/            # Configuration loading (Viper)\n│   ├── queue/             # Kafka client\n│   ├── database/          # PostgreSQL/Redis clients\n│   ├── notification/      # Core notification logic\n│   ├── channels/          # Channel-specific logic\n│   ├── monitoring/        # Prometheus metrics\n├── api/\n│   ├── proto/             # gRPC protobuf definitions\n│   │   └── gen/           # Generated protobuf code\n│   ├── grpc/              # gRPC service implementation\n│   └── rest/              # REST API handlers\n├── examples/\n│   └── grpc-client/       # Example gRPC client\n├── scripts/\n│   └── generate-proto.sh  # Protobuf code generation\n├── Dockerfile             # Docker configuration\n├── docker-compose.yml     # Multi-service orchestration\n├── Makefile              # Development commands\n├── prometheus.yml         # Prometheus configuration\n├── config.env.example     # Environment configuration example\n├── go.mod                 # Go module dependencies\n├── README.md              # This file\n```\n\n## Setup Instructions\n\n### Prerequisites:\n- Go 1.23+\n- Docker and Docker Compose\n- Protocol Buffers compiler (`protoc`)\n- Accounts for third-party providers (SendGrid, Twilio, Firebase)\n\n### Installation:\n```bash\ngit clone https://github.com/your-repo/notification-system.git\ncd notification-system\n\n# Install development dependencies\nmake dev-deps\n\n# Generate protobuf code\nmake proto\n\n# Build all services\nmake build\n```\n\n### Configuration:\n1. Copy the example configuration:\n```bash\ncp config.env.example .env\n```\n\n2. Update the `.env` file with your configuration:\n```env\nDB_HOST=localhost\nDB_PORT=5432\nDB_USER=postgres\nDB_PASSWORD=secret\nREDIS_ADDR=localhost:6379\nKAFKA_BROKERS=localhost:9092\nSENDGRID_API_KEY=your-sendgrid-key\nTWILIO_ACCOUNT_SID=your-twilio-sid\nTWILIO_AUTH_TOKEN=your-twilio-token\nFIREBASE_CREDENTIALS_PATH=/path/to/firebase-credentials.json\n```\n\n### Running Locally:\n\n#### Using Docker Compose (Recommended):\n```bash\n# Start all services including dependencies\nmake docker-up\n\n# View logs\nmake docker-logs\n\n# Stop all services\nmake docker-down\n```\n\n#### Manual Setup:\n```bash\n# Start dependencies\ndocker-compose up -d postgres redis kafka\n\n# Start services manually\nmake run-api          # Start API server (REST + gRPC)\nmake run-email        # Start email service\nmake run-sms          # Start SMS service\nmake run-push         # Start push service\n```\n\n## API Endpoints\n\n### REST API (Port 8080)\n\n#### POST /api/v1/notifications\nCreate a new notification\n```json\n{\n  \"user_id\": \"123\",\n  \"channel\": \"email\",\n  \"recipient\": \"user@example.com\",\n  \"subject\": \"Welcome!\",\n  \"body\": \"Thank you for joining.\",\n  \"priority\": 1\n}\n```\n\n#### GET /api/v1/notifications/{id}\nRetrieve notification status\n```json\n{\n  \"id\": \"uuid\",\n  \"user_id\": \"123\",\n  \"channel\": \"email\",\n  \"recipient\": \"user@example.com\",\n  \"subject\": \"Welcome!\",\n  \"body\": \"Thank you for joining.\",\n  \"status\": \"sent\",\n  \"created_at\": \"2023-01-01T00:00:00Z\"\n}\n```\n\n#### GET /health\nHealth check endpoint\n\n#### GET /metrics\nPrometheus metrics endpoint\n\n### gRPC API (Port 9090)\n\nThe service exposes a full gRPC API defined in `api/proto/notification.proto`. Key methods include:\n\n- `CreateNotification` - Create a new notification\n- `GetNotification` - Retrieve notification by ID\n- `ListNotifications` - List notifications with filtering\n- `UpdateNotificationStatus` - Update notification status\n- `GetUserPreferences` - Get user notification preferences\n- `UpdateUserPreferences` - Update user preferences\n\n#### Example gRPC Usage:\n```bash\n# Test gRPC API with example client\nmake grpc-test\n\n# List available gRPC services\nmake grpc-list\n\n# Manual gRPC call with grpcurl\ngrpcurl -plaintext -d '{\"user_id\":\"123\",\"channel\":\"CHANNEL_EMAIL\",\"recipient\":\"test@example.com\",\"subject\":\"Test\",\"body\":\"Hello gRPC!\"}' localhost:9090 notification.v1.NotificationService/CreateNotification\n```\n\n## Development Commands\n\nThe project includes a comprehensive Makefile for development:\n\n```bash\nmake help           # Show all available commands\nmake build          # Build all services\nmake proto          # Generate protobuf code\nmake test           # Run tests\nmake lint           # Run linter\nmake docker-up      # Start with Docker Compose\nmake docker-down    # Stop all services\nmake grpc-test      # Test gRPC API\nmake example-rest   # Test REST API\n```\n\n## Scaling Considerations\n\n- **Concurrency**: Leverages Go's goroutines and channels for high concurrency.\n- **Horizontal Scaling**: Deploy multiple instances of services with a load balancer.\n- **Queue Partitioning**: Uses Kafka partitions for load distribution.\n- **Database Optimization**: PostgreSQL with proper indexing and connection pooling.\n- **Caching**: Redis for user preferences and rate limiting.\n- **API Gateway**: Support for both REST and gRPC protocols.\n\n## Monitoring and Logging\n\n- **Metrics**: Prometheus endpoints expose delivery rates, latency, and error metrics.\n- **Dashboards**: Grafana visualizes system performance.\n- **Logging**: Structured logging with Zap to stdout.\n- **Health Checks**: Each service exposes health endpoints.\n- **gRPC Reflection**: Enabled for development tools.\n\n## Service Architecture\n\n### API Service (Ports 8080 + 9090)\n- **REST API** (8080): HTTP endpoints for web clients\n- **gRPC API** (9090): High-performance binary protocol for service-to-service communication\n- Validates requests and publishes to Kafka queue\n- Manages user preferences and rate limiting\n\n### Email Service\n- Consumes email notifications from Kafka\n- Integrates with SendGrid for email delivery\n- Updates notification status in database\n\n### SMS Service\n- Consumes SMS notifications from Kafka\n- Integrates with Twilio for SMS delivery\n- Handles delivery reports and status updates\n\n### Push Service\n- Consumes push notifications from Kafka\n- Integrates with Firebase Cloud Messaging\n- Supports both Android and iOS devices\n\n## gRPC Protocol Buffer Schema\n\nThe gRPC API is defined using Protocol Buffers with the following key message types:\n\n```protobuf\n// Create notification request\nmessage CreateNotificationRequest {\n  string user_id = 1;\n  Channel channel = 2;      // EMAIL, SMS, PUSH\n  string recipient = 3;\n  string subject = 4;\n  string body = 5;\n  Priority priority = 6;    // LOW, MEDIUM, HIGH\n  google.protobuf.Timestamp scheduled_at = 7;\n  map\u003cstring, string\u003e metadata = 10;\n}\n\n// Notification entity\nmessage Notification {\n  string id = 1;\n  string user_id = 2;\n  Channel channel = 3;\n  string recipient = 4;\n  string subject = 5;\n  string body = 6;\n  NotificationStatus status = 7;  // PENDING, SENT, DELIVERED, FAILED\n  google.protobuf.Timestamp created_at = 14;\n  // ... additional fields\n}\n```\n\n## Database Schema\n\n### Users Table\n- id (UUID, Primary Key)\n- email (VARCHAR, Unique)\n- phone (VARCHAR)\n- push_token (VARCHAR)\n\n### Notifications Table\n- id (UUID, Primary Key)\n- user_id (UUID, Foreign Key)\n- channel (VARCHAR)\n- recipient (VARCHAR)\n- subject (VARCHAR)\n- body (TEXT)\n- status (VARCHAR)\n- external_id (VARCHAR)\n- retry_count (INTEGER)\n- created_at (TIMESTAMP)\n\n### User Preferences Table\n- id (UUID, Primary Key)\n- user_id (UUID, Foreign Key)\n- channel (VARCHAR)\n- enabled (BOOLEAN)\n- frequency (VARCHAR)\n\n## Future Improvements\n\n- Add support for in-app notifications\n- Implement rate limiting using golang.org/x/time/rate\n- Introduce A/B testing for notification content\n- Enhance retry logic with exponential backoff\n- Add notification templates with variables\n- Implement webhook delivery confirmations\n- Add notification scheduling and batching\n- Add authentication and authorization to gRPC API\n- Implement streaming APIs for real-time updates\n\n## Contributing\nContributions are welcome! Follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature-name`)\n3. Commit changes (`git commit -m 'Add feature'`)\n4. Push to the branch (`git push origin feature-name`)\n5. Open a pull request\n\n## License\nThis project is licensed under the MIT License. See the LICENSE file for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexnthnz%2Fnotification-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexnthnz%2Fnotification-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexnthnz%2Fnotification-system/lists"}