A microservices-based patient management system built with Spring Boot, featuring API Gateway, authentication, billing, and analytics services.
The system consists of multiple microservices communicating via REST APIs and gRPC:
- API Gateway (Port 8080): Spring Cloud Gateway with rate limiting, circuit breaker, and authentication
- Patient Service (Port 4000): Core patient management with PostgreSQL database
- Auth Service (Port 4005): JWT-based authentication service
- Billing Service (Port 4001, gRPC 9001): Billing operations via gRPC
- Analytics Service (Port 4002): Event-driven analytics consuming Kafka messages
- PostgreSQL: Two databases for patient-service and auth-service
- Kafka: Message broker for event-driven communication
- Redis: Caching and rate limiting for API Gateway
- LocalStack: Local AWS services for development (Lambda, S3, DynamoDB, etc.)
- Java 21
- Maven 3.9+
- Docker & Docker Compose
- AWS CLI (for LocalStack integration)
docker-compose up -dThis starts all required services:
- PostgreSQL databases (ports 5000, 5001)
- Kafka (ports 9092, 9094)
- Redis (port 6379)
- LocalStack (port 4566)
The services will be built and started automatically via Docker Compose. Alternatively, you can run them individually:
# Patient Service
cd patient-service && mvn spring-boot:run
# Auth Service
cd auth-service && mvn spring-boot:run
# Billing Service
cd billing-service && mvn spring-boot:run
# Analytics Service
cd analytics-service && mvn spring-boot:run
# API Gateway
cd api-gateway && mvn spring-boot:run- API Gateway: http://localhost:8080/actuator/health
- Patient Service: http://localhost:4000/actuator/health
- Auth Service: http://localhost:4005/actuator/health
- Swagger UI: http://localhost:8080/swagger-ui.html
- OpenAPI Docs: http://localhost:8080/v3/api-docs
curl -X POST http://localhost:8080/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"user","password":"password"}'curl http://localhost:8080/api/patients \
-H "Authorization: Bearer YOUR_TOKEN_HERE"For detailed API testing, see api-requests/README.md.
GET /api/patients- List all patientsPOST /api/patients- Create a new patientGET /api/patients/{id}- Get patient by IDPUT /api/patients/{id}- Update patientDELETE /api/patients/{id}- Delete patient
POST /api/auth/login- Login and get JWT tokenPOST /api/auth/validate- Validate JWT token
POST /api/billing/accounts- Create billing account (gRPC)
GET /api/analytics/stats- Get analytics statistics
patient-management/
├── api-gateway/ # Spring Cloud Gateway
├── patient-service/ # Patient CRUD operations
├── auth-service/ # Authentication & authorization
├── billing-service/ # Billing operations (gRPC)
├── analytics-service/ # Event-driven analytics
├── infrastructure/ # AWS CDK for LocalStack
├── integration-tests/ # End-to-end integration tests
├── api-requests/ # HTTP request files for testing
└── docker-compose.yaml # Local development environment
# Build all services
mvn clean install
# Build specific service
cd patient-service && mvn clean package# Run all tests
mvn test
# Run integration tests
cd integration-tests && mvn testLocalStack provides local AWS services for development and testing.
aws configure
# AWS Access Key ID: test
# AWS Secret Access Key: test
# Default region: us-east-1
# Default output format: jsoncd infrastructure
./localstack-deploy.sh# List Lambda functions
aws --endpoint-url=http://localhost:4566 lambda list-functions
# List S3 buckets
aws --endpoint-url=http://localhost:4566 s3 lsKey environment variables can be set in docker-compose.yaml:
SPRING_DATASOURCE_URL: Database connection URLSPRING_KAFKA_BOOTSTRAP_SERVERS: Kafka broker addressJWT_SECRET: Secret key for JWT token signingREDIS_HOST&REDIS_PORT: Redis connection detailsLOCALSTACK_AUTH_TOKEN: LocalStack authentication token (optional, set via environment variable)
docker-compose.yaml and data.sql are for development only.
Always change these in production environments:
- Database passwords
- JWT secrets
- LocalStack auth tokens
- Default user credentials
| Service | Port | Description |
|---|---|---|
| API Gateway | 8080 | Main entry point |
| Patient Service | 4000 | Patient management API |
| Auth Service | 4005 | Authentication API |
| Billing Service | 4001 | REST API |
| Billing Service | 9001 | gRPC API |
| Analytics Service | 4002 | Analytics API |
| PostgreSQL (Patient) | 5000 | Patient database |
| PostgreSQL (Auth) | 5001 | Auth database |
| Kafka | 9092, 9094 | Message broker |
| Redis | 6379 | Cache & rate limiting |
| LocalStack | 4566 | AWS services |
All services expose Spring Boot Actuator endpoints:
/actuator/health- Health check/actuator/metrics- Application metrics/actuator/prometheus- Prometheus metrics/actuator/gateway/routes- API Gateway routes (gateway only)
- Rate Limiting: 10 requests/second per IP (configurable)
- Circuit Breaker: Resilience4j with fallback responses
- Request/Response Logging: Comprehensive logging with request IDs
- CORS Support: Configured for cross-origin requests
- Security Headers: Adds security headers to responses
The integration-tests module contains comprehensive end-to-end tests:
- Authentication & Authorization (6 tests)
- CRUD Operations (8 tests)
- Validation & Error Handling (8 tests)
- Edge Cases & Boundary Tests (3 tests)
- Data Integrity (1 test)
- Performance Tests (1 test)
Total: 26 integration tests
See integration-tests/README.md for details.
- API Gateway README - API Gateway features and configuration
- API Requests README - HTTP request files for testing
- Integration Tests README - Test suite documentation
# Restart Docker service
sudo systemctl restart docker
# Check container logs
docker-compose logs -f [service-name]
# Rebuild containers
docker-compose up -d --buildEnsure PostgreSQL containers are running:
docker-compose psVerify Kafka is accessible:
docker-compose logs kafkacurl http://localhost:4566/_localstack/health[Add your license information here]
[Add contribution guidelines here]