Spring Boot project structure

When you create a Spring Boot project (for example, via Spring Initializr), you get a pre-made structure out of the box. It’s not a random jumble of files and folders — it’s a thoughtful template that makes development and maintenance easier. Let’s break down its parts.

Project structure

Say we created a new project named demo. Here’s the structure you’ll see:

demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/demo/
│   │   │       └── DemoApplication.java
│   │   ├── resources/
│   │       ├── static/
│   │       ├── templates/
│   │       ├── application.properties
│   │       └── application.yml
│   ├── test/
│       ├── java/
│       │   └── com/example/demo/
│       │       └── DemoApplicationTests.java
│       └── resources/
├── mvnw
├── mvnw.cmd
├── pom.xml
└── README.md

Let’s walk through all of this.

src/main/java

Probably no surprise here — this is where your main application code lives. Inside you’ll see a package layout based on the Group and Artifact ID you set when creating the project. For example, if your Group ID is com.example and Artifact ID is demo, you’ll get the com/example/demo directory.

Main application class Every Spring Boot project has a main class annotated with @SpringBootApplication. In our case it’s DemoApplication.java:

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

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

It’s not just some “main” class. This class:

1. Starts the application.
2. Enables auto-configuration via the @SpringBootApplication annotation.
3. Performs component scanning (hey there, @ComponentScan).

How to organize code inside src/main/java

Typically code is split into three layers: Controller, Service, Repository.

• Controller: handles HTTP requests.
• Service: where the business logic lives.
• Repository: handles database interaction.

Example structure:

src/main/java/com/example/demo/
├── controller/
├── service/
└── repository/

This layout isn’t mandatory, but it’s a widely accepted convention.

src/main/resources

This folder is for all non-code resources your app needs. If you have JSON files, HTML templates, config files, or images, they belong here.

• static/: put static assets here, like CSS, JavaScript, images.
• templates/: this holds HTML templates (for example, if you use Thymeleaf).
• application.properties or application.yml: the main config file — we already poked around this a bit in earlier lectures.

Example contents of application.properties:

server.port=8081
spring.datasource.url=jdbc:mysql://localhost:3306/demo
spring.datasource.username=root
spring.datasource.password=secret

Note: Spring automatically picks up resources from this folder. You don’t need to write extra code to load them — Spring magic handles it.

src/test/java

Testing? Yeah, you can’t avoid it. This directory is your best friend for writing unit, integration, and functional tests.

Example test for the main application class:

package com.example.demo;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class DemoApplicationTests {
    @Test
    void contextLoads() {
    }
}

Spring Boot auto-configures the test environment, so you can be confident your app behaves as expected.

Top-level project files

At the root of the project you’ll find a few important files:

• pom.xml or build.gradle — the dependency management tool (Maven or Gradle). This is where you add libraries your project needs.
• mvnw and mvnw.cmd — the Maven wrapper. These let you run Maven even if it’s not installed on your machine.
• README.md — usually contains instructions on how to work with the project (honestly, few people actually read it).

Main application class

@SpringBootApplication — three annotations in one

@SpringBootApplication is a combo of three annotations:

1. @Configuration — lets the class be used as a source of bean definitions.
2. @EnableAutoConfiguration — turns on Spring Boot’s magical auto-configuration.
3. @ComponentScan — automatically discovers components annotated with @Component, @Service, @Repository, etc.

That’s why adding @SpringBootApplication gives you all the basics you need to run a Spring Boot app.

Config file: application.properties or application.yml

Difference between application.properties and application.yml

• application.properties: the classic key-value format.
• application.yml: a more modern format that supports nested structures.

Example application.properties:

server.port=8080
spring.application.name=DemoApplication

Example application.yml:

server:
  port: 8080
spring:
  application:
    name: DemoApplication

YAML is often easier to read, especially for complex configs.

Now you have a good idea of what’s inside a Spring Boot project. As they say, “don’t judge a project by its folder names until you peek into its src/main/java.” Let’s keep going and dive even deeper into the world of Spring Boot!