Spring Boot Master Project

A comprehensive Spring Boot learning project that demonstrates all core concepts, best practices, and industry-standard patterns for mastering the Spring Boot framework.

🎯 Project Overview

This is a User Management System that showcases enterprise-level Spring Boot architecture. The application demonstrates how modern web applications are built using Spring Boot's powerful features and industry-standard patterns.

What You'll Master:

• Complete request-response flow from browser to database
• Enterprise layered architecture patterns
• Spring Boot's "magic" - auto-configuration and dependency injection
• Real-world API design and implementation
• Security, caching, validation, and testing strategies

Current Application Status: ✅ Running and Ready for Interaction

• Main Application: http://localhost:8080/api/v1
• Interactive API Documentation: http://localhost:8080/api/v1/swagger-ui.html
• Database Console: http://localhost:8080/api/v1/h2-console
• Health Monitoring: http://localhost:8080/api/v1/actuator

🏗️ Architecture

The project follows a layered architecture pattern:

┌─────────────────┐
│   Controller    │  ← REST API endpoints, request/response handling
├─────────────────┤
│    Service      │  ← Business logic, transaction management
├─────────────────┤
│   Repository    │  ← Data access layer, JPA queries
├─────────────────┤
│    Entity       │  ← JPA entities, database mapping
└─────────────────┘

🚀 Features Demonstrated

Core Spring Boot Concepts

• Auto-configuration - Leveraging Spring Boot's intelligent defaults
• Dependency Injection - Constructor injection and @Autowired
• Component Scanning - Automatic bean discovery and registration
• Profiles - Environment-specific configurations (dev, prod)

Web Layer

• REST Controllers - @RestController, @RequestMapping
• HTTP Methods - GET, POST, PUT, DELETE operations
• Request/Response Handling - @RequestBody, @PathVariable, @RequestParam
• Validation - Bean validation with JSR-303 annotations
• Exception Handling - Global exception handling with @RestControllerAdvice

Data Layer

• JPA/Hibernate - Object-relational mapping
• Spring Data JPA - Repository pattern implementation
• Custom Queries - JPQL and native SQL queries
• Relationships - One-to-Many, Many-to-One mappings
• Pagination - Page and Sort support
• Transactions - @Transactional management

Security

• Authentication - Basic authentication setup
• Authorization - Role-based access control
• Password Encoding - BCrypt password hashing
• Security Configuration - Custom security rules

Caching

• Method Caching - @Cacheable, @CacheEvict
• Cache Configuration - CacheManager setup
• Performance Optimization - Reducing database calls

Testing

• Unit Testing - JUnit 5, Mockito
• Integration Testing - @SpringBootTest
• Web Layer Testing - @WebMvcTest, MockMvc
• Repository Testing - @DataJpaTest

Documentation

• API Documentation - Swagger/OpenAPI integration
• Interactive API Explorer - Swagger UI
• Code Documentation - Comprehensive JavaDoc

Monitoring & Operations

• Actuator - Health checks, metrics, info endpoints
• Logging - Structured logging configuration
• Profiles - Environment-specific settings

📂 Project Structure

src/
├── main/
│   ├── java/com/springboot/master/
│   │   ├── SpringBootMasterApplication.java    # Main application class
│   │   ├── config/                            # Configuration classes
│   │   │   ├── SecurityConfig.java           # Security configuration
│   │   │   ├── OpenApiConfig.java            # Swagger configuration
│   │   │   └── AppConfig.java                # General configuration
│   │   ├── controller/                       # REST controllers
│   │   │   └── UserController.java           # User management endpoints
│   │   ├── service/                          # Business logic layer
│   │   │   └── UserService.java              # User business operations
│   │   ├── repository/                       # Data access layer
│   │   │   ├── UserRepository.java           # User data operations
│   │   │   └── PostRepository.java           # Post data operations
│   │   ├── entity/                           # JPA entities
│   │   │   ├── User.java                     # User entity
│   │   │   ├── Post.java                     # Post entity
│   │   │   └── UserRole.java                 # User role enum
│   │   ├── dto/                              # Data Transfer Objects
│   │   │   ├── CreateUserDto.java            # User creation request
│   │   │   └── UserResponseDto.java          # User response
│   │   └── exception/                        # Exception handling
│   │       ├── ResourceNotFoundException.java
│   │       ├── DuplicateResourceException.java
│   │       └── GlobalExceptionHandler.java
│   └── resources/
│       ├── application.properties            # Main configuration
│       ├── application-dev.properties        # Development profile
│       └── application-prod.properties       # Production profile
└── test/                                     # Test classes
    └── java/com/springboot/master/
        ├── SpringBootMasterApplicationTests.java
        ├── controller/
        ├── service/
        └── repository/

🛠️ Technologies Used

• Java 17 - Programming language
• Spring Boot 3.2.0 - Framework
• Spring Data JPA - Data persistence
• Spring Security - Authentication & authorization
• H2 Database - In-memory database (development)
• MySQL - Production database
• Maven - Build tool
• JUnit 5 - Testing framework
• Mockito - Mocking framework
• Swagger/OpenAPI - API documentation

🚀 Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.6 or higher
• IDE (IntelliJ IDEA, Eclipse, VS Code)

Running the Application

1. Clone the repository

   git clone <repository-url>
   cd spring-boot-master

2. Run with Maven

   mvn spring-boot:run

3. Run with IDE

   • Import the project as a Maven project
   • Run SpringBootMasterApplication.java

Access Points

• Application: http://localhost:8080/api/v1
• H2 Console: http://localhost:8080/api/v1/h2-console
• Swagger UI: http://localhost:8080/api/v1/swagger-ui.html
• API Docs: http://localhost:8080/api/v1/api-docs
• Actuator: http://localhost:8080/api/v1/actuator

📖 Learning Path

1. Basic Concepts

• Start with SpringBootMasterApplication.java - understand auto-configuration
• Explore application.properties - configuration management
• Review entity classes - JPA mapping concepts

2. Web Layer

• Study UserController.java - REST API patterns
• Understand request/response handling
• Learn about validation and error handling

3. Business Layer

• Examine UserService.java - service layer patterns
• Understand transaction management
• Learn about caching mechanisms

4. Data Layer

• Review repository interfaces - Spring Data JPA
• Study custom queries and pagination
• Understand entity relationships

5. Security

• Explore SecurityConfig.java - security configuration
• Understand authentication and authorization
• Learn about password encoding

6. Testing

• Study test classes - different testing strategies
• Understand mocking and integration testing
• Learn about test slices (@WebMvcTest, @DataJpaTest)

7. Advanced Topics

• Configuration and profiles
• Caching strategies
• API documentation
• Monitoring with Actuator

🔧 Configuration

Profiles

• Development: Uses H2 in-memory database, detailed logging
• Production: Configured for MySQL, optimized logging

Database Configuration

# Development (H2)
spring.datasource.url=jdbc:h2:mem:testdb
spring.h2.console.enabled=true

# Production (MySQL)
spring.datasource.url=jdbc:mysql://localhost:3306/springboot_master_prod
spring.jpa.hibernate.ddl-auto=validate

🧪 Testing

Run tests with Maven:

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=UserControllerTest

# Run with coverage
mvn test jacoco:report

📚 Key Learning Points

Best Practices Demonstrated

1. Layered Architecture - Clear separation of concerns
2. DTO Pattern - Separate API contracts from domain models
3. Exception Handling - Centralized error management
4. Input Validation - Comprehensive validation strategies
5. Security - Authentication and authorization
6. Testing - Comprehensive test coverage
7. Documentation - Self-documenting APIs
8. Configuration - Environment-specific settings

Spring Boot Concepts Covered

• Auto-configuration and starters
• Dependency injection and IoC
• Data access with Spring Data JPA
• RESTful web services
• Security implementation
• Caching mechanisms
• Testing strategies
• Monitoring and management

🤝 Contributing

This project is designed for learning purposes. Feel free to:

• Add new features to practice concepts
• Improve existing implementations
• Add more comprehensive tests
• Enhance documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔄 How the Application Works - Complete Flow Explanation

Understanding the Spring Boot "Magic"

Spring Boot's power lies in its auto-configuration and convention over configuration approach. When you start the application, here's what happens:

Application Startup Process

1. @SpringBootApplication annotation triggers:

   • Component Scanning: Finds all classes with @Component, @Service, @Repository, @Controller
   • Auto-Configuration: Automatically configures beans based on classpath dependencies
   • Configuration Processing: Loads properties from application.properties

2. Dependency Injection Container is created:

   • Spring creates instances of all your classes (beans)
   • Injects dependencies automatically (constructor injection in our project)
   • Manages the lifecycle of these objects

3. Embedded Server Starts:

   • Tomcat server starts on port 8080
   • Web context is initialized
   • All REST endpoints become available

User Interaction Flow - From Browser to Database

1. User Makes HTTP Request

User Browser → http://localhost:8080/api/v1/users

2. Spring Boot Request Processing

HTTP Request → DispatcherServlet → UserController

What Happens:

• DispatcherServlet (Spring's front controller) receives the request
• HandlerMapping determines which controller method should handle it
• UserController.getAllUsers() method is invoked

3. Controller Layer (UserController.java)

@GetMapping
public ResponseEntity<Page<UserResponseDto>> getAllUsers() {
    // Controller validates request, delegates to service
    Page<UserResponseDto> users = userService.getAllUsers(pageable);
    return ResponseEntity.ok(users);
}

Responsibilities:

• Handle HTTP requests/responses
• Validate input parameters
• Convert between DTOs and HTTP responses
• Return appropriate HTTP status codes

4. Service Layer (UserService.java)

@Cacheable("users")
@Transactional(readOnly = true)
public Page<UserResponseDto> getAllUsers(Pageable pageable) {
    // Business logic, caching, transaction management
    Page<User> users = userRepository.findAll(pageable);
    return users.map(this::convertToDto);
}

Responsibilities:

• Implement business logic
• Manage transactions (@Transactional)
• Handle caching (@Cacheable)
• Convert entities to DTOs
• Orchestrate multiple repository calls if needed

5. Repository Layer (UserRepository.java)

public interface UserRepository extends JpaRepository<User, Long> {
    // Spring Data JPA generates implementation automatically
    Page<User> findAll(Pageable pageable);
}

What Spring Boot Does:

• Proxy Creation: Spring creates a proxy implementation of your interface
• Method Translation: findAll() becomes SELECT * FROM users
• Result Mapping: Database rows are mapped to User entities

6. Database Interaction

-- Generated SQL query
SELECT u.id, u.username, u.email, u.created_at, u.role 
FROM users u 
LIMIT 20 OFFSET 0;

What Happens:

• Hibernate (JPA implementation) generates SQL
• HikariCP (connection pool) manages database connections
• H2 Database executes the query
• Results are mapped back to Java objects

7. Response Journey Back

Database → Repository → Service → Controller → HTTP Response → User Browser

Real User Interaction Examples

Example 1: Creating a New User

1. User Action:

curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "email": "john@example.com",
    "password": "securePassword123",
    "role": "USER"
  }'

2. Spring Boot Processing:

// Controller receives request
@PostMapping
public ResponseEntity<UserResponseDto> createUser(@Valid @RequestBody CreateUserDto dto) {
    // @Valid triggers validation
    UserResponseDto user = userService.createUser(dto);
    return ResponseEntity.status(HttpStatus.CREATED).body(user);
}

3. Validation Process:

// JSR-303 validation annotations are checked
@NotBlank(message = "Username is required")
@Size(min = 3, max = 50)
private String username;

@Email(message = "Invalid email format")
private String email;

4. Service Layer Processing:

@Transactional
public UserResponseDto createUser(CreateUserDto dto) {
    // Check for duplicate email
    if (userRepository.existsByEmail(dto.getEmail())) {
        throw new DuplicateResourceException("Email already exists");
    }
    
    // Encode password
    String encodedPassword = passwordEncoder.encode(dto.getPassword());
    
    // Create and save user
    User user = new User(dto.getUsername(), dto.getEmail(), encodedPassword, dto.getRole());
    User savedUser = userRepository.save(user);
    
    // Clear cache
    cacheManager.getCache("users").clear();
    
    return convertToDto(savedUser);
}

5. Database Transaction:

INSERT INTO users (username, email, password, role, created_at) 
VALUES ('john_doe', 'john@example.com', '$2a$10$...', 'USER', '2024-01-15 10:30:00');

Example 2: Error Handling in Action

User sends invalid data:

{
  "username": "",
  "email": "invalid-email",
  "password": "123"
}

Spring Boot Response:

// Global Exception Handler catches validation errors
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
        // Extract validation errors
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error -> 
            errors.put(error.getField(), error.getDefaultMessage())
        );
        
        return ResponseEntity.badRequest().body(new ErrorResponse("Validation failed", errors));
    }
}

User receives:

{
  "message": "Validation failed",
  "errors": {
    "username": "Username is required",
    "email": "Invalid email format",
    "password": "Password must be at least 8 characters"
  },
  "timestamp": "2024-01-15T10:30:00"
}

Caching in Action

First request to get users:

@Cacheable("users")
public Page<UserResponseDto> getAllUsers(Pageable pageable) {
    // Hits database, stores result in cache
    log.info("Fetching users from database");
    return userRepository.findAll(pageable).map(this::convertToDto);
}

Second identical request:

// Returns cached result, no database hit
log.info("Returning cached users");

Cache eviction on user creation:

@CacheEvict(value = "users", allEntries = true)
public UserResponseDto createUser(CreateUserDto dto) {
    // Cache is cleared to ensure fresh data
}

Security Integration

When user accesses protected endpoint:

1. Request Interception:

// Security filter chain intercepts request
@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) {
        return http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/v1/users/**").authenticated()
            )
            .httpBasic(Customizer.withDefaults())
            .build();
    }
}

2. Authentication Check:

• User provides credentials in request header
• Spring Security validates against configured user details
• If valid, request proceeds to controller
• If invalid, returns 401 Unauthorized

Performance Optimizations

1. Connection Pooling:

# HikariCP configuration
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5

2. JPA Optimization:

@Entity
@Table(name = "users", indexes = {
    @Index(name = "idx_user_email", columnList = "email"),
    @Index(name = "idx_user_username", columnList = "username")
})
public class User {
    // Database indexes improve query performance
}

3. Pagination:

// Instead of loading all users
public Page<UserResponseDto> getAllUsers(Pageable pageable) {
    // Only loads requested page (e.g., 20 records)
    return userRepository.findAll(pageable).map(this::convertToDto);
}

Monitoring and Observability

Actuator endpoints provide insights:

• Health Check: GET /actuator/health

{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "diskSpace": { "status": "UP" }
  }
}

• Metrics: GET /actuator/metrics/http.server.requests

{
  "name": "http.server.requests",
  "measurements": [
    { "statistic": "COUNT", "value": 150 },
    { "statistic": "TOTAL_TIME", "value": 45.2 }
  ]
}

Key Takeaways for Users

1. Spring Boot Handles Complexity: You write simple code, Spring Boot handles the infrastructure
2. Convention Over Configuration: Follow naming conventions, get functionality for free
3. Layered Architecture: Each layer has specific responsibilities and concerns
4. Automatic Wiring: Dependencies are injected automatically based on types
5. Production Ready: Built-in security, monitoring, and performance optimizations
6. Developer Friendly: Auto-reload, embedded server, comprehensive error messages

This is how Spring Boot transforms complex enterprise application development into a streamlined, productive experience while maintaining professional-grade quality and performance.

🎓 Next Steps

After mastering this project, consider exploring:

• Microservices with Spring Cloud
• Reactive Programming with Spring WebFlux
• Message Queues with Spring AMQP
• NoSQL Databases with Spring Data MongoDB
• GraphQL APIs with Spring GraphQL
• Containerization with Docker
• Cloud Deployment with Spring Cloud

---

Happy Learning! 🚀