LearnAI ToolsCareerPractice BuildsPlayContact
Lesson 618 min read

Project Structure

Understand the folder layout of a generated Spring Boot project, including the main application class and the src/main/resources folder.

Introduction

Once Spring Initializr generates your project and you unzip it, you are met with a folder structure that looks unfamiliar at first but follows a strict, predictable convention. Understanding this layout up front will save you a lot of confusion later — Spring Boot relies on "convention over configuration," meaning files are found automatically as long as they live in the expected place.

The Generated Folder Layout

A freshly generated Maven-based Spring Boot project looks like this:

Project Structure
demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/programinds/demo/
│   │   │       └── DemoApplication.java
│   │   └── resources/
│   │       ├── application.properties
│   │       ├── static/
│   │       └── templates/
│   └── test/
│       └── java/
│           └── com/programinds/demo/
│               └── DemoApplicationTests.java
├── pom.xml
├── mvnw
├── mvnw.cmd
└── .gitignore

This layout follows the standard Maven directory structure: application code lives under `src/main/java`, non-Java resources live under `src/main/resources`, and tests live under a parallel `src/test/java` tree.

The Main Application Class

Inside `src/main/java`, nested inside your chosen package, sits the generated entry-point class — in this example, `DemoApplication.java`.

DemoApplication.java
package com.programinds.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);
    }
}
Why Package Placement Matters

Component scanning starts from the package of your main class and searches downward through sub-packages. If you place a controller or service in a sibling or parent package, Spring Boot will not find it automatically.

src/main/resources

This folder holds everything that is not compiled Java code but still needs to end up on the classpath at runtime:

  • application.properties (or application.yml) — the central configuration file for the application.
  • static/ — static web assets (CSS, JavaScript, images) served directly if building a traditional web app.
  • templates/ — server-side view templates (e.g. Thymeleaf) if the project renders HTML on the server.

The Test Folder

Spring Initializr also generates a starter test class that verifies the application context loads successfully — a useful smoke test even before you have written any real code.

DemoApplicationTests.java
package com.programinds.demo;


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


@SpringBootTest
class DemoApplicationTests {


    @Test
    void contextLoads() {
    }
}

Common Mistakes

Avoid These Mistakes
  • Moving the main application class out of the root package, which breaks automatic component scanning for classes in sibling packages.
  • Placing configuration files outside src/main/resources, where Spring Boot will not find them on the classpath.
  • Deleting the generated test class instead of building on it — it is a useful baseline sanity check.

Best Practices

  • Organize code into sub-packages by feature or layer (e.g. controller, service, repository) beneath the main package.
  • Keep the main application class minimal — it should only bootstrap the app.
  • Never rename or move application.properties without updating any tooling that expects it in the default location.

Frequently Asked Questions

Yes, the class and file name can be anything you like, as long as it is annotated with @SpringBootApplication and stays in (or above) your root package for component scanning to work correctly.

Spring Boot will not automatically discover it, because component scanning only looks in the package of the main class and its sub-packages. You would need to explicitly configure @ComponentScan to include it.

No, the src/main/java and src/main/resources convention is identical for both Maven and Gradle projects — only the build file (pom.xml vs build.gradle) differs.

Key Takeaways

  • Spring Boot follows the standard Maven layout: src/main/java for code, src/main/resources for configuration and assets.
  • The main @SpringBootApplication class should stay in the root package for component scanning to work.
  • application.properties (or application.yml) lives in src/main/resources and drives configuration.
  • A generated test class verifies the application context loads successfully.

Summary

The Spring Boot project structure is predictable by design: code under src/main/java, configuration and static assets under src/main/resources, and tests under a parallel src/test/java tree. Understanding this convention is the key to understanding how Spring Boot finds everything automatically. Next, you will dig into exactly how that automatic discovery — auto-configuration — actually works.

Next Lesson →

Auto-Configuration Explained