{"id":30674409,"url":"https://github.com/kenzycodex/spring-notification-service","last_synced_at":"2026-04-11T10:37:40.174Z","repository":{"id":312053117,"uuid":"1046066467","full_name":"kenzycodex/spring-notification-service","owner":"kenzycodex","description":"Production-ready Spring Boot microservice for multi-channel notifications including email, real-time WebSocket, and RabbitMQ queue-based messaging with JWT authentication","archived":false,"fork":false,"pushed_at":"2025-08-28T07:58:37.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T14:44:54.417Z","etag":null,"topics":["docker","email","java","jwt","maven","messaging","microservice","mysql","notifications","rabbitmq","realtime","rest-api","smtp","spring-boot","websocket"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kenzycodex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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-08-28T06:19:48.000Z","updated_at":"2025-08-28T07:58:41.000Z","dependencies_parsed_at":"2025-08-28T14:48:05.297Z","dependency_job_id":"e16fd5dd-b57a-40c0-9567-0d0fc2f5e796","html_url":"https://github.com/kenzycodex/spring-notification-service","commit_stats":null,"previous_names":["kenzycodex/spring-notification-service"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kenzycodex/spring-notification-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fspring-notification-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fspring-notification-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fspring-notification-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fspring-notification-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kenzycodex","download_url":"https://codeload.github.com/kenzycodex/spring-notification-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2Fspring-notification-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273086469,"owners_count":25043339,"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-09-01T02:00:09.058Z","response_time":120,"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":["docker","email","java","jwt","maven","messaging","microservice","mysql","notifications","rabbitmq","realtime","rest-api","smtp","spring-boot","websocket"],"created_at":"2025-09-01T07:08:38.004Z","updated_at":"2025-12-30T21:33:23.654Z","avatar_url":"https://github.com/kenzycodex.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Notification \u0026 Messaging Service\n\nA production-ready Spring Boot microservice for handling notifications via multiple channels including email, real-time\nWebSocket, and queue-based messaging with RabbitMQ.\n\n## 🚀 Features\n\n- **📧 Email Notifications**: SMTP-based email sending with HTML/plain text support\n- **⚡ Real-time Notifications**: WebSocket-based real-time messaging via STOMP\n- **🔄 Queue-based Processing**: RabbitMQ message queuing with fallback to async processing\n- **🔒 JWT Authentication**: Secure API access with JWT tokens\n- **💾 Database Support**: MySQL for production, H2 for development\n- **🐳 Docker Ready**: Full containerization with Docker Compose\n- **📊 Monitoring**: Spring Boot Actuator with health checks and metrics\n- **🧪 Comprehensive Testing**: Unit tests with JUnit 5 and Mockito\n\n## 📋 Prerequisites\n\n- **Java 17+**\n- **Maven 3.6+**\n- **Docker \u0026 Docker Compose** (optional, for containerized setup)\n- **MySQL 8.0+** (for production)\n- **RabbitMQ 3.12+** (optional, falls back to async processing)\n\n## 🛠️ Quick Start\n\n### 1. Clone and Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/kenzycodex/spring-notification-service.git\n\n\ncd spring-notification-service\n\n# Run with Maven (uses H2 database)\nmvn spring-boot:run\n\n# 🎉 Service running at http://localhost:8080\n```\n\n### 2. Run Locally (Development)\n\n```bash\n# Build the project\nmvn clean compile\n\n# Run with development profile (uses H2 database)\nmvn spring-boot:run\n\n# Or specify profile explicitly\nmvn spring-boot:run -Dspring-boot.run.profiles=dev\n```\n\nThe service will start on `http://localhost:8080`\n\n### 3. Run with Docker Compose (Production-like)\n\n```bash\n# Create environment file\necho \"MAIL_USERNAME=your-email@gmail.com\" \u003e .env\necho \"MAIL_PASSWORD=your-app-password\" \u003e\u003e .env\necho \"MAIL_FROM=noreply@yourcompany.com\" \u003e\u003e .env\necho \"JWT_SECRET=your-very-long-secure-secret-key-here\" \u003e\u003e .env\n\n# Start all services\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f notification-service\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable                 | Description               | Default                 | Required      |\n|--------------------------|---------------------------|-------------------------|---------------|\n| `SPRING_PROFILES_ACTIVE` | Active profile (dev/prod) | `dev`                   | No            |\n| `DB_HOST`                | MySQL host                | `mysql`                 | Prod only     |\n| `DB_PORT`                | MySQL port                | `3306`                  | Prod only     |\n| `DB_NAME`                | Database name             | `notification_db`       | Prod only     |\n| `DB_USERNAME`            | Database username         | `notification_user`     | Prod only     |\n| `DB_PASSWORD`            | Database password         | `notification_password` | Prod only     |\n| `RABBITMQ_HOST`          | RabbitMQ host             | `rabbitmq`              | No            |\n| `RABBITMQ_USERNAME`      | RabbitMQ username         | `notification_user`     | No            |\n| `RABBITMQ_PASSWORD`      | RabbitMQ password         | `notification_password` | No            |\n| `MAIL_HOST`              | SMTP host                 | `smtp.gmail.com`        | No            |\n| `MAIL_USERNAME`          | SMTP username             | -                       | Yes for email |\n| `MAIL_PASSWORD`          | SMTP password             | -                       | Yes for email |\n| `MAIL_FROM`              | From email address        | -                       | No            |\n| `JWT_SECRET`             | JWT secret key            | -                       | Yes           |\n| `JWT_EXPIRATION`         | JWT expiration (seconds)  | `3600`                  | No            |\n\n### Email Setup (Gmail Example)\n\n1. Enable 2-Factor Authentication on your Gmail account\n2. Generate an App Password: `Google Account \u003e Security \u003e App passwords`\n3. Use your Gmail address as `MAIL_USERNAME`\n4. Use the generated app password as `MAIL_PASSWORD`\n\n## 🔌 API Endpoints\n\n### Authentication\n\n#### Register User\n\n```http\nPOST /api/auth/register\nContent-Type: application/json\n\n{\n  \"username\": \"testuser\",\n  \"password\": \"password123\",\n  \"email\": \"user@example.com\"\n}\n```\n\n#### Login\n\n```http\nPOST /api/auth/login\nContent-Type: application/json\n\n{\n  \"username\": \"testuser\",\n  \"password\": \"password123\"\n}\n```\n\nResponse:\n\n```json\n{\n  \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"type\": \"Bearer\",\n  \"username\": \"testuser\",\n  \"message\": \"Authentication successful\"\n}\n```\n\n### Notifications (Require Authentication)\n\nAdd header: `Authorization: Bearer {your-jwt-token}`\n\n#### Send Email Notification\n\n```http\nPOST /api/notify/email\nContent-Type: application/json\n\n{\n  \"to\": \"recipient@example.com\",\n  \"subject\": \"Test Notification\",\n  \"body\": \"This is a test email notification\",\n  \"html\": false\n}\n```\n\n#### Send Real-time Notification\n\n```http\nPOST /api/notify/realtime\nContent-Type: application/json\n\n{\n  \"topic\": \"user-notifications\",\n  \"message\": \"New message for you!\",\n  \"recipient\": \"username\"\n}\n```\n\n#### Send Queue Notification\n\n```http\nPOST /api/notify/queue\nContent-Type: application/json\n\n{\n  \"type\": \"EMAIL\",\n  \"recipient\": \"user@example.com\",\n  \"message\": \"Subject|Email body content\",\n  \"priority\": 0\n}\n```\n\n### Health Check\n\n```http\nGET /api/notify/health\n```\n\n## 🔗 WebSocket Connection\n\nConnect to WebSocket endpoint for real-time notifications:\n\n```javascript\n// Connect to WebSocket\nconst socket = new SockJS('http://localhost:8080/ws');\nconst stompClient = Stomp.over(socket);\n\nstompClient.connect({}, function (frame) {\n    console.log('Connected: ' + frame);\n    \n    // Subscribe to a topic\n    stompClient.subscribe('/topic/user-notifications', function (message) {\n        const notification = JSON.parse(message.body);\n        console.log('Received notification:', notification);\n    });\n});\n```\n\n## 🧪 Testing\n\n### Run Unit Tests\n\n```bash\nmvn test\n```\n\n### Run Integration Tests\n\n```bash\nmvn verify\n```\n\n### Test Coverage\n\n```bash\nmvn jacoco:report\n```\n\n### Manual API Testing\n\nUse the provided Postman collection or curl commands:\n\n```bash\n# Register user\ncurl -X POST http://localhost:8080/api/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"username\":\"testuser\",\"password\":\"password123\",\"email\":\"test@example.com\"}'\n\n# Login and get token\nTOKEN=$(curl -X POST http://localhost:8080/api/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"username\":\"testuser\",\"password\":\"password123\"}' | jq -r '.token')\n\n# Send email notification\ncurl -X POST http://localhost:8080/api/notify/email \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -d '{\"to\":\"test@example.com\",\"subject\":\"Test\",\"body\":\"Hello World\"}'\n```\n\n## 🔧 Development\n\n### IDE Setup (IntelliJ IDEA)\n\n1. **Import Project**: File → Open → Select `pom.xml`\n2. **Set JDK**: File → Project Structure → Project → SDK: Java 17\n3. **Enable Annotation Processing**: Settings → Build → Compiler → Annotation Processors\n4. **Install Plugins**: Spring Boot, Database Navigator (optional)\n\n### Code Style\n\n- Follow Spring Boot best practices\n- Use meaningful variable and method names\n- Add JavaDoc for public methods\n- Maintain test coverage above 80%\n\n### Adding New Features\n\n1. **Create Feature Branch**: `git checkout -b feature/your-feature`\n2. **Add Service Layer**: Business logic in `service` package\n3. **Add Controller**: REST endpoints in `controller` package\n4. **Add Tests**: Unit tests for all new code\n5. **Update Documentation**: README and API docs\n\n## 🚀 Deployment\n\n### Production Deployment\n\n1. **Build JAR**:\n\n```bash\nmvn clean package -DskipTests\n```\n\n1. **Run with Production Profile**:\n\n```bash\njava -jar -Dspring.profiles.active=prod target/notification-service-1.0.0.jar\n```\n\n1. **Docker Deployment**:\n\n```bash\n# Build image\ndocker build -t notification-service:1.0.0 .\n\n# Run container\ndocker run -d \\\n  -p 8080:8080 \\\n  -e SPRING_PROFILES_ACTIVE=prod \\\n  -e DB_HOST=your-mysql-host \\\n  -e MAIL_USERNAME=your-email@gmail.com \\\n  -e MAIL_PASSWORD=your-app-password \\\n  -e JWT_SECRET=your-secure-secret \\\n  notification-service:1.0.0\n```\n\n### Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: notification-service\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: notification-service\n  template:\n    metadata:\n      labels:\n        app: notification-service\n    spec:\n      containers:\n        - name: notification-service\n          image: notification-service:1.0.0\n          ports:\n            - containerPort: 8080\n          env:\n            - name: SPRING_PROFILES_ACTIVE\n              value: \"prod\"\n            - name: DB_HOST\n              value: \"mysql-service\"\n          # Add other environment variables\n```\n\n## 📊 Monitoring\n\n### Health Checks\n\n- Application: `GET /actuator/health`\n- Database: Included in health endpoint\n- RabbitMQ: Included if configured\n\n### Metrics\n\n- Prometheus metrics: `/actuator/prometheus`\n- Application metrics: `/actuator/metrics`\n\n### Logging\n\n- Log files: `logs/notification-service.log`\n- Log levels configurable per environment\n- Structured JSON logging in production\n\n## 🔒 Security\n\n- JWT tokens for API authentication\n- Secure password encoding with BCrypt\n- CORS configuration for cross-origin requests\n- Input validation on all endpoints\n- SQL injection prevention with JPA\n- XSS protection with proper encoding\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **Email Not Sending**\n    - Check SMTP credentials\n    - Verify Gmail app password\n    - Check firewall settings\n\n2. **Database Connection Failed**\n    - Verify MySQL is running\n    - Check connection parameters\n    - Ensure database exists\n\n3. **RabbitMQ Connection Issues**\n    - Service falls back to async processing\n    - Check RabbitMQ server status\n    - Verify connection credentials\n\n4. **JWT Token Issues**\n    - Ensure JWT_SECRET is set\n    - Check token expiration\n    - Verify Authorization header format\n\n### Debug Mode\n\nEnable debug logging:\n\n```yaml\nlogging:\n  level:\n    com.notificationservice: DEBUG\n    org.springframework.web: DEBUG\n```\n\n## 📚 Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   REST Client   │────│  NotificationAPI │────│   JWT Security  │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n                                │\n                   ┌────────────┴────────────┐\n                   │  NotificationService    │\n                   └────────────┬────────────┘\n                                │\n        ┌───────────────────────┼───────────────────────┐\n        │                       │                       │\n┌───────▼──────┐    ┌──────────▼─────────┐    ┌────────▼────────┐\n│ EmailService │    │ WebSocketService   │    │  QueueService   │\n└──────────────┘    └────────────────────┘    └─────────────────┘\n        │                       │                       │\n┌───────▼──────┐    ┌──────────▼─────────┐    ┌────────▼────────┐\n│     SMTP     │    │    WebSocket       │    │    RabbitMQ     │\n└──────────────┘    └────────────────────┘    └─────────────────┘\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit changes (`git commit -m 'Add amazing feature'`)\n4. Push to branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 📞 Support\n\nFor support and questions:\n\n- Create an issue in the repository\n- Email: kenzycodex@gmail.com\n- Documentation: README Docs\n\n---\n\n## ✅ Deployment Checklist\n\n- [ ] Java 17+ installed\n- [ ] Maven dependencies resolved\n- [ ] Database configuration set\n- [ ] Email SMTP configured\n- [ ] JWT secret configured\n- [ ] RabbitMQ setup (optional)\n- [ ] Docker images built\n- [ ] Environment variables set\n- [ ] Health checks passing\n- [ ] Tests passing\n- [ ] Security review completed","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenzycodex%2Fspring-notification-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenzycodex%2Fspring-notification-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenzycodex%2Fspring-notification-service/lists"}