Spring Boot Project Structure Explained (Real-World Best Practices)

Leave a Comment / Spring Boot Basics / By

When you start with Spring Boot, creating a project is simple. Understanding why the project is structured the way it is is what turns a beginner into a confident Spring Boot engineer.

This guide explains the Spring Boot project structure clearly — starting from the basics and extending to real-world, production-grade best practices used in professional applications.

Why Spring Boot Project Structure Matters

Many Spring Boot problems are not caused by complex bugs, but by incorrect project structure, such as:

  • Classes placed outside the base package
  • Misconfigured configuration classes
  • Components not being scanned
  • Resources not loading correctly

If you understand the project structure properly:

  • Auto-configuration works as expected
  • Dependency injection behaves correctly
  • Applications scale cleanly
  • Debugging becomes much easier

Typical Spring Boot Project Structure

A standard Spring Boot project looks like this:

springboot-demo
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com.example.demo
│   │   │       ├── DemoApplication.java
│   │   │       ├── controller
│   │   │       ├── service
│   │   │       ├── repository
│   │   │       └── config
│   │   └── resources
│   │       ├── application.properties
│   │       ├── static
│   │       └── templates
│   └── test
│       └── java
│           └── com.example.demo
└── pom.xml

Let’s understand what each part does and why it exists.

DemoApplication.java – The Application Entry Point

This is the starting point of your Spring Boot application.

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

What happens here:

  • Starts the embedded server (Tomcat by default)
  • Enables auto-configuration
  • Triggers component scanning
  • Loads application configuration

Important rule:
All your application packages must be under the same base package as this class.

Correct structure:

com.example.demo
├── DemoApplication
├── controller
├── service

Incorrect structure (very common mistake):

com.example
├── DemoApplication
com.example.api
├── controller   ❌ Not scanned

This mistake often causes issues like controllers not loading or beans not being created.

Controller Package – Handling HTTP Requests

Controllers handle incoming HTTP requests from browsers, frontend apps, or API clients.

@RestController
@RequestMapping("/api")
public class HealthController {

    @GetMapping("/health")
    public String health() {
        return "OK";
    }
}

Best practices:

  • Controllers should be thin
  • No business logic
  • Only request handling and validation

Bad practice:

  • Writing database or business logic inside controllers

Good practice:

  • Delegate work to the service layer

Service Package – Business Logic Layer

This is where real application logic belongs.

@Service
public class UserService {

    public String getUserStatus() {
        return "ACTIVE";
    }
}

Why this layer is important:

  • Keeps controllers clean
  • Makes code testable
  • Improves maintainability

In production systems, most logic changes happen here.

Repository Package – Database Access Layer

Repositories handle database interactions.

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

Spring Boot automatically:

  • Generates implementations
  • Manages database connections
  • Handles transactions

Real-world tip:
Avoid writing manual JDBC logic when Spring Data JPA can manage it safely and efficiently.

Config Package – Application Configuration

Configuration classes control how your application behaves.

Typical use cases:

  • Security configuration
  • CORS configuration
  • Swagger / OpenAPI setup
  • Custom beans
@Configuration
public class AppConfig {

    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

Misplacing configuration classes is a common cause of BeanCreationException.

Resources Folder – Configuration and Static Files

application.properties or application.yml

This file controls:

  • Server port
  • Database configuration
  • Logging levels
  • Active profiles

Example:

server.port=8081
spring.profiles.active=dev

In production, many issues are fixed by changing configuration, not code.

static Folder

Used for:

  • CSS
  • JavaScript
  • Images

Mostly used when serving frontend content from Spring Boot.

templates Folder

Used for server-side rendered views (Thymeleaf).

Common in MVC-based applications.

Test Folder – Automated Testing

src/test/java

Contains:

  • Unit tests
  • Integration tests

Even basic tests help prevent production issues and regressions.

pom.xml – Dependency and Build Management

The pom.xml file defines:

  • Spring Boot version
  • Dependencies
  • Build configuration
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Production advice:
Always align dependency versions with the Spring Boot version to avoid runtime failures.

Recommended Production Package Structure

For real-world applications, a more scalable structure looks like this:

com.company.product
├── config
├── controller
├── service
├── repository
├── domain
├── dto
├── exception
└── util

This structure scales well when:

  • Teams grow
  • Features increase
  • Microservices are introduced

Common Project Structure Mistakes

  • Placing classes outside the base package
  • Mixing configuration and business logic
  • Writing logic inside controllers
  • Using one giant service class
  • Hardcoding environment values

These mistakes often lead to startup failures and maintenance problems.

How Project Structure Helps Debug Real Issues

Many common Spring Boot issues are caused by poor structure, such as:

  • Application not starting
  • Beans not detected
  • JPA entities not created
  • Configuration not loading correctly

Understanding structure allows you to debug faster and more confidently.

What to Learn Next

After understanding project structure, the next logical topics are:

  • application.properties vs application.yml
  • Spring Profiles (dev, test, prod)
  • Bean creation and lifecycle
  • Common startup failures

These topics build directly on this foundation.

Final Thoughts

Spring Boot follows convention over configuration, but conventions only help when you understand them.

Master the project structure early, and every Spring Boot problem becomes easier to solve.

Related Spring Boot Guides

Understanding the Spring Boot project structure is the foundation for building reliable and production-ready applications. You may also find the following guides helpful as you continue learning:

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *