Project structure walkthrough in Spring Boot - Deep Dive

Overview - Project structure walkthrough

What is it?

A Spring Boot project structure is the organized layout of files and folders that make up a Spring Boot application. It includes source code, configuration files, resources, and build scripts arranged in a way that helps the application run smoothly. This structure follows conventions that make it easy for developers to find and manage parts of the application.

Why it matters

Without a clear project structure, developers would struggle to understand, maintain, and extend the application. It would be like trying to find a book in a messy library with no order. A good structure saves time, reduces errors, and helps teams work together efficiently.

Where it fits

Before learning project structure, you should understand basic Java programming and how Spring Boot works at a high level. After mastering project structure, you can learn about advanced Spring Boot features like dependency injection, security, and microservices architecture.

Mental Model

Core Idea

A Spring Boot project structure is like a well-organized toolbox where each drawer holds specific tools needed to build and run the application efficiently.

Think of it like...

Imagine a kitchen where ingredients, utensils, and appliances are stored in separate cabinets and drawers. This organization helps you cook faster and cleaner. Similarly, a Spring Boot project keeps code, settings, and resources in separate folders so developers can work smoothly.

SpringBootProject
├── src
│   ├── main
│   │   ├── java
│   │   │   └── com.example.app
│   │   │       ├── Application.java
│   │   │       ├── controller
│   │   │       ├── service
│   │   │       └── repository
│   │   ├── resources
│   │   │   ├── application.properties
│   │   │   └── static
│   │   │       ├── css
│   │   │       └── js
│   └── test
│       └── java
│           └── com.example.app
├── pom.xml (or build.gradle)
└── README.md

Build-Up - 7 Steps

1

Foundation

Understanding the src folder basics

Concept: Learn what the src folder is and why it is the heart of the project.

The src folder contains all the source code and resources needed to build the application. It is divided into main and test. The main folder holds the application code and resources, while the test folder holds code for testing the application.

Result

You know where to put your Java classes and resource files so Spring Boot can find and use them.

Understanding the src folder layout is essential because it separates production code from test code, keeping the project clean and manageable.

2

Foundation

Role of the main/java directory

Concept: Discover where your Java code lives and how package structure organizes it.

Inside src/main/java, you place your Java classes organized by packages, usually starting with your domain name reversed (e.g., com.example.app). This helps avoid name conflicts and groups related classes like controllers, services, and repositories.

Result

You can organize your code logically, making it easier to find and maintain.

Knowing how to structure packages prevents confusion and supports Spring Boot's component scanning to find your classes automatically.

3

Intermediate

Purpose of the resources folder

Concept: Learn what kinds of files go into src/main/resources and why.

The resources folder holds configuration files like application.properties or application.yml, static files like images, CSS, and JavaScript, and templates for views. Spring Boot loads these files automatically at runtime.

Result

You can customize your application settings and serve static content correctly.

Separating code from resources allows flexible configuration and easy updates without changing Java code.

4

Intermediate

Understanding the test directory

Concept: Explore how test code is organized separately from main code.

The src/test/java folder mirrors the main/java structure but contains test classes. This separation ensures tests do not get mixed with production code and can be run independently.

Result

You can write and run tests safely without affecting the main application.

Keeping tests separate encourages good testing practices and helps maintain code quality.

5

Intermediate

Build files and dependency management

Concept: Understand the role of pom.xml or build.gradle in managing project dependencies and build process.

The pom.xml (for Maven) or build.gradle (for Gradle) file lists libraries your project needs and defines how to compile and package your app. These files automate downloading dependencies and building the project.

Result

You can add features by including libraries without manual downloads and build your app consistently.

Using build tools simplifies managing external code and ensures everyone on the team builds the project the same way.

6

Advanced

How Spring Boot auto-configuration fits in

🤔Before reading on: do you think Spring Boot requires manual setup of every component or does it automate some parts? Commit to your answer.

Concept: Learn how Spring Boot uses the project structure to automatically configure components.

Spring Boot scans the packages under your main application class to find components like controllers and services. It uses the resources folder for configuration and static content. This automatic setup reduces boilerplate code and speeds development.

Result

Your application starts with minimal configuration and works out of the box.

Understanding auto-configuration helps you organize your project so Spring Boot can find and wire components correctly.

7

Expert

Customizing project structure and pitfalls

🤔Before reading on: can you freely move source folders anywhere in the project without configuration? Commit to your answer.

Concept: Explore how to customize the default structure and what problems can arise.

While Spring Boot has conventions, you can customize source and resource locations in build files. However, changing defaults requires updating configuration and can confuse tools or other developers. Misplaced files may cause runtime errors or missing resources.

Result

You gain flexibility but must manage complexity carefully.

Knowing the defaults and risks of customization prevents hard-to-debug errors and keeps projects maintainable.

Under the Hood

Spring Boot uses a classpath scanning mechanism that starts from the package of the main application class. It looks for annotations like @Controller, @Service, and @Repository to create and wire beans automatically. The build tool compiles Java code from src/main/java and packages resources from src/main/resources into the final executable jar. Tests in src/test/java are compiled and run separately. The build file manages dependencies and build lifecycle, ensuring all parts are correctly assembled.

Why designed this way?

The structure follows Maven conventions to leverage existing tools and community knowledge. It balances convention over configuration, reducing setup time while allowing customization. This design evolved to support rapid development, modular code, and easy testing, which were challenges in traditional Java projects.

Project Structure Flow

[Build Tool] --> compiles --> [src/main/java] --> classes
                 packages --> [src/main/resources] --> resources
                 tests --> [src/test/java] --> test classes

[Spring Boot] --> scans --> [main application package]
                 loads --> [configuration files]
                 serves --> [static resources]

[Output] --> executable jar with all compiled code and resources

Myth Busters - 4 Common Misconceptions

Quick: Do you think you can put your Java classes anywhere in the project and Spring Boot will find them automatically? Commit to yes or no.

Common Belief: I can place my Java classes in any folder and Spring Boot will detect them.

Reality: Spring Boot only scans packages under the main application class's package by default. Classes outside this hierarchy are ignored unless explicitly configured.

Why it matters: Placing classes outside scanned packages causes them not to be registered, leading to missing functionality and runtime errors.

Quick: Do you think the resources folder is only for static files like images and CSS? Commit to yes or no.

Common Belief: The resources folder is just for static files and does not affect application behavior.

Reality: Resources include configuration files like application.properties that control how the application runs, not just static content.

Why it matters: Ignoring configuration files in resources can cause misconfiguration and unexpected application behavior.

Quick: Do you think customizing the project structure is always safe and recommended? Commit to yes or no.

Common Belief: Changing the default project structure is easy and improves the project.

Reality: Customizing structure requires careful configuration changes; otherwise, it breaks build and runtime behavior.

Why it matters: Improper customization leads to build failures, missing classes, and wasted debugging time.

Quick: Do you think tests can be mixed with production code in the same folder? Commit to yes or no.

Common Belief: Tests can be placed alongside production code without issues.

Reality: Tests should be in a separate folder to avoid being included in the production build and to keep code organized.

Why it matters: Mixing tests with production code bloats the application and complicates maintenance.

Expert Zone

1

Spring Boot's component scanning is sensitive to the package of the main application class; placing it too high or too low affects which beans are detected.

2

Resource files can be overridden by placing files with the same name in different resource folders, enabling environment-specific configurations.

3

Build tools like Maven and Gradle cache dependencies and build artifacts, so changes in project structure sometimes require cleaning the build to avoid stale results.

When NOT to use

Avoid heavily customizing the default project structure unless you have a strong reason and understand the build tool configurations. For very large or modular projects, consider using multi-module Maven or Gradle projects instead of a flat structure.

Production Patterns

In production, teams often follow the standard structure strictly to ensure consistency. They separate layers clearly (controller, service, repository), use profiles for environment-specific resources, and automate builds with CI/CD pipelines that rely on this structure.

Connections

Modular Programming

Builds-on

Understanding project structure helps grasp modular programming by showing how code is grouped into logical units that can be developed and maintained independently.

Software Architecture

Same pattern

Project structure reflects architectural principles like separation of concerns and layering, which are key to building scalable and maintainable software.

Library Organization in a Physical Library

Similar pattern

Just as books are organized by categories and shelves for easy access, project files are organized by function and type to help developers find and use them efficiently.

Common Pitfalls

#1 Placing Java classes outside the main application package hierarchy.

Wrong approach:

src/main/java/com/other/app/ExtraService.java (when main app is com.example.app)

Correct approach:

src/main/java/com/example/app/service/ExtraService.java

Root cause:

Misunderstanding that Spring Boot scans only packages under the main application class by default.

#2 Putting test classes inside src/main/java instead of src/test/java.

Wrong approach:

src/main/java/com/example/app/TestUserService.java

Correct approach:

src/test/java/com/example/app/TestUserService.java

Root cause:

Confusing production code with test code locations, leading to tests being included in production builds.

#3 Modifying the build file without updating source/resource paths accordingly.

Wrong approach:

Moving src/main/resources to src/resources without changing build.gradle or pom.xml

Correct approach:

Either keep default src/main/resources or update build configuration to new path

Root cause:

Not understanding that build tools rely on conventions unless explicitly configured.

Key Takeaways

A clear Spring Boot project structure separates code, resources, and tests to keep the application organized and maintainable.

The src/main/java folder holds your Java code organized by packages, which Spring Boot scans to find components automatically.

Resources like configuration files and static content live in src/main/resources and are loaded by Spring Boot at runtime.

Build files like pom.xml or build.gradle manage dependencies and automate building, ensuring consistent project assembly.

Following conventions avoids common errors and makes it easier for teams to collaborate and maintain the application.