Spring Boot Microservices Architecture

A comprehensive, production-grade Spring Boot microservices project demonstrating modern distributed system design patterns, featuring multiple services working together through REST APIs, gRPC, Kafka, and event-driven messaging.

🏗️ Project Overview

This is a complete microservices ecosystem built with Spring Boot 3.3.5+ / 4.0.0, Java 17, and showcasing real-world patterns like API Gateway routing, JWT authentication, inter-service communication via gRPC, and event-driven architecture using Kafka. Perfect for learning enterprise-grade backend development.

📁 Project Structure & Service Ports

SpringbootMicroServicesProject/
├── api-gateway/                        # API Gateway (HTTP Port: 4004)
│   ├── Spring Boot: 3.3.5
│   ├── Routes: /auth/** → auth-service:4005
│   │            /api/patients/** → patient-service:4000
│   └── src/main/resources/application.yml
│
├── patient-service/                    # Patient CRUD (HTTP Port: 4000)
│   ├── Spring Boot: 3.3.5
│   ├── Java: 17
│   ├── gRPC Client: calls billing-service:9001
│   ├── Kafka Producer: publishes patient events
│   └── src/main/resources/application.properties
│
├── auth-service/                       # JWT Auth Service (HTTP Port: 4005)
│   ├── Spring Boot: 3.3.5
│   ├── Java: 17
│   ├── Endpoints: /auth/login, /auth/validate
│   └── src/main/resources/application.properties
│
├── billing-service/                    # Billing via gRPC
│   ├── Spring Boot: 4.0.0
│   ├── Java: 17
│   ├── HTTP Port: 4001
│   ├── gRPC Port: 9001
│   ├── gRPC Server: handles billing requests
│   └── src/main/resources/application.properties
│
├── analytics-service/                  # Kafka Consumer (HTTP Port: 4002)
│   ├── Spring Boot: 3.3.5
│   ├── Java: 17
│   ├── Kafka Consumer: processes patient events
│   └── src/main/resources/application.properties
│
├── api-requests/                       # API Testing Collection
│   └── *.http files for IntelliJ/VS Code
│
├── grpc-requests/                      # gRPC Testing
│   └── *.proto files for testing
│
└── docker-compose.yml                  # Infrastructure Setup

🛠️ Tech Stack (Verified from Code)

Core Framework & Languages

• Java 17 - Main programming language (JDK 17) - Verified
• Spring Boot 3.3.5 - Patient, Auth, Analytics, API Gateway services
• Spring Boot 4.0.0 - Billing Service
• Spring Web - REST API development
• Spring Data JPA - Object-relational mapping
• Spring Validation - Request validation

Persistence

• PostgreSQL - Primary relational database
• Spring Data JPA - ORM layer

Service Communication

• gRPC 1.69.0 - Binary RPC protocol
  • Patient Service → Billing Service (Port 9001)
• Protocol Buffers 3.25.5 - Service contracts

Event-Driven Architecture

• Apache Kafka - Event streaming platform
• Kafka Producer - Patient Service publishes events
• Kafka Consumer - Analytics Service consumes events

Security & Authentication

• Spring Security - Security framework
• JWT - Stateless authentication
• BCrypt - Password hashing

Infrastructure & Containerization

• Docker - Container images for each service
• Docker Compose - Multi-container orchestration
• PostgreSQL (Containerized) - Database container
• Kafka (Containerized) - Message broker

Build & Development

• Maven 3 - Build automation
• Spring Boot DevTools - Hot reload
• Springdoc OpenAPI 2.6.0 - Swagger/OpenAPI documentation

🚀 Service Ports Reference (Verified from Config Files)

Service	HTTP Port	gRPC Port	Tech	Spring Boot
API Gateway	4004	-	Spring Cloud Gateway	3.3.5
Patient Service	4000	-	REST + gRPC Client	3.3.5
Auth Service	4005	-	JWT Auth	3.3.5
Billing Service	4001	9001	gRPC Server	4.0.0
Analytics Service	4002	-	Kafka Consumer	3.3.5

Note: All services use Java 17 as configured in pom.xml files

🔧 Getting Started

Prerequisites

• Java 17 JDK (Required - verified in all pom.xml files)
• Maven 3.8+
• Docker & Docker Desktop
• Git

Quick Start

1. Clone Repository

git clone https://github.com/PeddintiPraneeth759/SpringbootMicroServicesProject.git
cd SpringbootMicroServicesProject

2. Start Infrastructure

docker-compose up -d
docker-compose ps

3. Build All Services

mvn clean install

4. Run Services (Separate Terminals - Use Correct Ports!)

Terminal 1: API Gateway (Port 4004)

cd api-gateway && mvn spring-boot:run

Terminal 2: Patient Service (Port 4000)

cd patient-service && mvn spring-boot:run

Terminal 3: Auth Service (Port 4005)

cd auth-service && mvn spring-boot:run

Terminal 4: Billing Service (Port 4001 + gRPC 9001)

cd billing-service && mvn spring-boot:run

Terminal 5: Analytics Service (Port 4002)

cd analytics-service && mvn spring-boot:run

5. Verify Services

# Access API Gateway (Port 4004)
curl http://localhost:4004/auth/login

# Check Patient Service through Gateway
curl http://localhost:4004/api/patients

# Check Individual Services
curl http://localhost:4000/patients        # Patient Service
curl http://localhost:4005/                 # Auth Service  
curl http://localhost:4002/                 # Analytics Service
curl http://localhost:4001/                 # Billing Service (HTTP)

📚 API Endpoints

Authentication (via Gateway - Port 4004)

POST   /auth/login              # Get JWT token
POST   /auth/validate           # Validate token

Patient Service (via Gateway - Port 4004)

GET    /api/patients             # List patients
GET    /api/patients/{id}        # Get patient by ID
POST   /api/patients             # Create patient
PUT    /api/patients/{id}        # Update patient
DELETE /api/patients/{id}        # Delete patient

Full API Docs: http://localhost:4004/swagger-ui.html

🔐 Authentication Flow

1. Login (Auth Service - Port 4005)

curl -X POST http://localhost:4004/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

2. Use Token

curl -X GET http://localhost:4004/api/patients \
  -H "Authorization: Bearer <JWT_TOKEN>"

3. Validate Token

curl -X POST http://localhost:4004/auth/validate \
  -H "Authorization: Bearer <JWT_TOKEN>"

📡 Service Communication Patterns

REST API

• Client → API Gateway (4004)
• API Gateway → Patient Service (4000) / Auth Service (4005)

gRPC (Binary Protocol)

• Patient Service (4000) → Billing Service gRPC (9001)
• Type-safe message serialization via Protocol Buffers

Kafka (Event Streaming)

• Patient Service (4000): Publishes patient-events topic
• Analytics Service (4002): Consumes and processes events
• Event schema defined in Protobuf

🧪 Testing

Unit Tests

mvn test
cd patient-service && mvn test

Integration Tests

mvn verify

API Testing

Use files in api-requests/ directory for IntelliJ/VS Code HTTP testing

gRPC Testing

Use utilities in grpc-requests/ directory

🐛 Troubleshooting

Port Already in Use

lsof -i :4000   # Check Patient Service port
kill -9 <PID>   # Kill process

Database Connection Error

docker-compose logs postgres
# Check application.properties credentials

Kafka Issues

docker-compose logs kafka
docker exec kafka kafka-topics.sh --list --bootstrap-server localhost:9092

gRPC Connection Error (Port 9001)

netstat -an | grep 9001
# Verify Billing Service is running on port 4001
mvn clean compile  # Recompile proto files

Java Version Error

java -version  # Verify Java 17 is installed
update-alternatives --config java  # Switch to Java 17

📖 Documentation

• Swagger UI: http://localhost:4004/swagger-ui.html
• OpenAPI Spec: http://localhost:4004/v3/api-docs
• Service Ports Reference: See table above
• Proto Files: Contain gRPC service contracts

🤝 Contributing

git checkout -b feature/YourFeature
git commit -m 'Add YourFeature'
git push origin feature/YourFeature

Open a Pull Request!

🎯 Learning Outcomes

This project demonstrates:

• ✅ Microservices architecture (5 independent services)
• ✅ REST API development with Spring Boot
• ✅ gRPC & Protocol Buffers (Patient ↔ Billing communication)
• ✅ Kafka event streaming (Patient → Analytics)
• ✅ JWT authentication & authorization
• ✅ API Gateway pattern & routing
• ✅ Database design with JPA/Hibernate
• ✅ Docker containerization
• ✅ Service-to-service communication
• ✅ Error handling & validation

📄 License

MIT License - see LICENSE for details

👤 Author

Praneeth Peddinti

• GitHub: @PeddintiPraneeth759
• Email: [email protected]

🔗 Resources

• Spring Boot 3.3.5
• Spring Boot 4.0.0
• Java 17 Documentation
• gRPC Java Guide
• Apache Kafka
• Spring Cloud Gateway
• JWT Authentication

---

Last Updated: December 2025 Status: Active Development Java Requirement: Java 17+ Spring Boot Versions: 3.3.5 & 4.0.0 Verified Port Configuration: All ports tested and documented