🏢 Enterprise Microservices System

A modern, scalable microservices architecture built with Spring Boot 3.x/4.x, Spring Cloud, and PostgreSQL. This system demonstrates enterprise-grade patterns including service discovery, API gateway, centralized configuration, JWT authentication, and custom exception handling through a shared common library.

🏗️ Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API Gateway   │    │   Eureka Server │    │  Config Server  │
│     :8080       │    │     :8761       │    │     :8888       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    AUTH Service │    │ EMPLOYEE Service│    │ ADDRESS Service │
│     :8084       │    │     :8081       │    │     :8082       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   PostgreSQL    │
                    │     :5432       │
                    └─────────────────┘

🚀 Services

Service	Port	Description	Technology
API Gateway	8080	Single entry point, routing & authentication	Spring Cloud Gateway
Eureka Server	8761	Service discovery & registration	Netflix Eureka
Config Server	8888	Centralized configuration management	Spring Cloud Config
Auth Service	8084	User authentication & JWT token generation	Spring Security + JWT
Employee Service	8081	Employee management operations	Spring Boot + JPA
Address Service	8082	Address management for employees	Spring Boot + JPA

🛠️ Technology Stack

• Framework: Spring Boot 4.0.5, Spring Cloud 2025.1.1
• Language: Java 21
• Database: PostgreSQL
• Security: JWT Authentication, Spring Security
• Service Discovery: Netflix Eureka
• API Gateway: Spring Cloud Gateway
• Circuit Breaker: Resilience4j
• Configuration: Spring Cloud Config
• Build Tool: Maven
• Custom Library: common-lib for centralized exception handling

📦 Custom Library: common-lib

This project includes a custom common-lib library that provides centralized exception handling and reusable components across all microservices.

Features

• Centralized Exception Handling: GlobalExceptionHandler base class
• Custom Exceptions: Pre-built exception types for common scenarios
• Standardized Error Responses: Consistent error format across services
• Reusable Components: Common utilities and patterns

Available Exceptions

// Base exception classes provided by common-lib
- BadRequestException      // HTTP 400 - Invalid request data
- MissingParameterException // HTTP 400 - Required parameters missing
- CustomException          // Configurable HTTP status codes

Library Integration

Each microservice extends the GlobalExceptionHandler from common-lib:

@RestControllerAdvice
public class GlobalStatusHandler extends GlobalExceptionHandler {
    // Service-specific exception handling can be added here
}

Maven Dependency

<dependency>
    <groupId>com.commonlib</groupId>
    <artifactId>common-lib</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

🚀 Quick Start

Prerequisites

• Java 21
• Maven 3.6+
• PostgreSQL 12+
• Git

Database Setup

CREATE DATABASE employee;
CREATE USER root WITH PASSWORD 'test';
GRANT ALL PRIVILEGES ON DATABASE employee TO root;

Running the System

1. Clone the repository

   git clone <repository-url>
   cd microservices-system

2. Start services in order:

   # Terminal 1 - Eureka Server
   cd EUREKA-SERVER
   mvn spring-boot:run
   
   # Terminal 2 - Config Server
   cd CONFIG-SERVER
   mvn spring-boot:run
   
   # Terminal 3 - Auth Service
   cd AUTH
   mvn spring-boot:run
   
   # Terminal 4 - Employee Service
   cd EMPLOYEE
   mvn spring-boot:run
   
   # Terminal 5 - Address Service
   cd ADDRESS
   mvn spring-boot:run
   
   # Terminal 6 - API Gateway
   cd API-GATEWAY
   mvn spring-boot:run

📡 API Endpoints

Authentication Service (/auth)

• POST /auth/register-user - Register new user
• POST /auth/generate-token - Generate JWT token

Employee Service (/employees)

• POST /employees/save - Create new employee
• GET /employees/ - Get all employees
• GET /employees/{id} - Get employee by ID
• PUT /employees/update/{id} - Update employee
• DELETE /employees/delete/{id} - Delete employee
• GET /employees/get-by-emp-code-and-company-name - Search by code and company

Address Service (/addresses)

• POST /addresses/save - Create address(es)
• GET /addresses/all-address - Get all addresses
• GET /addresses/{addressId} - Get address by ID
• GET /addresses/empId/{empId} - Get addresses by employee ID
• PUT /addresses/update - Update address(es)
• DELETE /addresses/delete/{addressId} - Delete address

🔍 Service Discovery & Monitoring

Eureka Dashboard

• URL: http://localhost:8761
• View all registered services and their health status

Health Endpoints

# Gateway Health
GET http://localhost:8080/actuator/health

# Circuit Breaker Status
GET http://localhost:8080/actuator/circuitbreakers

# Service Metrics
GET http://localhost:8080/actuator/metrics

🛡️ Security Features

• JWT Authentication: Stateless token-based authentication
• API Gateway Security: Centralized authentication filter
• Circuit Breaker: Fault tolerance with Resilience4j
• Custom Exception Handling: Centralized error responses via common-lib

🔄 Circuit Breaker Configuration

The system implements circuit breakers for fault tolerance:

• Employee Service: 5s timeout, 50% failure rate threshold
• Address Service: 5s timeout, 50% failure rate threshold

Fallback Endpoints:

• Employee Service: /employeeServiceFallback
• Address Service: /addressServiceFallback

📊 Error Handling with common-lib

The common-lib provides standardized error responses across all services:

{
  "message": "Invalid Credentials",
  "status": 400,
  "timestamp": "2024-01-01T12:00:00Z",
  "path": "/auth/generate-token"
}

Exception Hierarchy

GlobalExceptionHandler (from common-lib)
├── BadRequestException
├── MissingParameterException
└── CustomException (configurable)

🔧 Configuration

Application Properties

• Database: PostgreSQL on localhost:5432
• Eureka: Service discovery on localhost:8761
• Config Server: Centralized config on localhost:8888

Port Allocation

Service	Port
API Gateway	8080
Auth Service	8084
Employee Service	8081
Address Service	8082
Eureka Server	8761
Config Server	8888

🏗️ Project Structure

microservices-system/
├── API-GATEWAY/          # Spring Cloud Gateway
├── AUTH/                 # Authentication Service
├── EMPLOYEE/             # Employee Management
├── ADDRESS/              # Address Management
├── EUREKA-SERVER/        # Service Discovery
├── CONFIG-SERVER/        # Configuration Management
└── common-lib/           # Shared Exception Library

🚀 Production Considerations

Environment Configuration

• Use environment-specific configuration files
• Configure production database connections
• Enable HTTPS and secure JWT secrets

Monitoring & Observability

• Implement distributed tracing (Zipkin/Sleuth)
• Add application performance monitoring
• Configure centralized logging

Deployment

• Containerize services with Docker
• Use Kubernetes for orchestration
• Configure load balancing for high availability

Security Best Practices

• Rotate JWT secrets regularly
• Implement rate limiting
• Add input validation and sanitization
• Configure CORS policies

🧪 Development Guidelines

Code Quality

• Follow Java coding conventions
• Write unit and integration tests
• Use SonarQube for code analysis
• Maintain API documentation

Common Library Development

• Add reusable exceptions to common-lib
• Update library version when making changes
• Test library integration across services
• Document new exception types

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request