Spring Boot Project Structure
A Spring Boot project generated by Spring Initializr follows a conventional Maven or Gradle layout: a build file (pom.xml or build.gradle) at the root, source code under src/main/java, resources under src/main/resources, and tests under src/test/java. This convention-over-configuration approach means build tools and IDEs can find your code without any extra configuration, because everyone agrees on the same folder shape.
Cricket analogy: Like every Test match ground following the same 22-yard pitch length and boundary rules regardless of country, Maven's standard directory layout means every Spring Boot project 'plays on the same pitch' so tools know where to look.
The Build File: pom.xml or build.gradle
The build file declares the project's parent (typically spring-boot-starter-parent, which manages dependency versions), the dependencies pulled in via starters, the Java version, and the plugin (spring-boot-maven-plugin or the Gradle equivalent) that repackages compiled classes into an executable JAR. Because spring-boot-starter-parent manages a curated Bill of Materials, you usually don't specify versions for individual Spring dependencies, avoiding version conflicts.
Cricket analogy: Like a national cricket board's central contract system setting fixed match fees for all centrally contracted players so franchises don't negotiate separately, spring-boot-starter-parent centrally fixes dependency versions so you don't negotiate them per-library.
Source Layout: Packages and the Main Class
The class annotated with @SpringBootApplication should sit in the root package (for example com.example.demo), because @ComponentScan by default scans that package and everything beneath it. Convention is to organize sub-packages by feature or layer, such as com.example.demo.controller, com.example.demo.service, and com.example.demo.repository, so component scanning automatically discovers @RestController, @Service, and @Repository beans without extra configuration.
Cricket analogy: Like placing the captain at the top of the batting order so their influence covers the whole innings, placing @SpringBootApplication at the root package ensures its component scan covers every package beneath it.
The resources Folder
src/main/resources holds non-Java assets: application.properties or application.yml for configuration, static/ for static web assets like CSS and JavaScript served directly, templates/ for server-side view templates such as Thymeleaf, and any database migration scripts under db/migration if you use Flyway. Everything in this folder is copied onto the classpath at build time, which is how Spring Boot finds application.yml at startup without any extra path configuration.
Cricket analogy: Like a team's dressing room holding kit, medical supplies, and strategy boards separate from the pitch itself, src/main/resources holds configuration and assets separate from the Java 'gameplay' code.
demo/
├── pom.xml
├── src/
│ ├── main/
│ │ ├── java/
│ │ │ └── com/example/demo/
│ │ │ ├── DemoApplication.java
│ │ │ ├── controller/
│ │ │ │ └── OrderController.java
│ │ │ ├── service/
│ │ │ │ └── OrderService.java
│ │ │ └── repository/
│ │ │ └── OrderRepository.java
│ │ └── resources/
│ │ ├── application.yml
│ │ ├── static/
│ │ └── templates/
│ └── test/
│ └── java/
│ └── com/example/demo/
│ └── DemoApplicationTests.java
└── target/If you move the @SpringBootApplication class out of the root package, or place feature packages as siblings rather than children of it, component scanning will silently miss beans outside its scope. You'll get confusing 'NoSuchBeanDefinitionException' errors at runtime unless you explicitly widen @ComponentScan's basePackages.
- Spring Boot projects follow the standard Maven/Gradle layout: src/main/java, src/main/resources, src/test/java.
- The build file (pom.xml or build.gradle) declares the parent, starter dependencies, and the packaging plugin.
- spring-boot-starter-parent centrally manages compatible dependency versions so you rarely specify them yourself.
- The @SpringBootApplication class should live in the root package so component scanning covers all sub-packages.
- Feature packages like controller, service, and repository are conventionally nested under the root package.
- src/main/resources holds application.yml, static assets, and templates, all copied onto the runtime classpath.
- Placing the main class outside the root package can cause components to be silently missed during scanning.
Practice what you learned
1. Where should the @SpringBootApplication class typically be placed?
2. What does spring-boot-starter-parent primarily provide?
3. What is typically stored in src/main/resources?
4. What can happen if the main class is moved outside the root package relative to feature packages?
5. Which folder holds unit and integration test source code by convention?
Was this page helpful?
You May Also Like
What Is Spring Boot?
An introduction to Spring Boot as an opinionated, production-ready extension of the Spring Framework that removes boilerplate configuration.
Spring Boot Starters
How starter dependencies bundle coherent, version-compatible sets of libraries so you can add capabilities like web or data access with one line.
The Spring Application Context
What the ApplicationContext is, how it manages the bean lifecycle, and how dependency injection resolves object graphs at startup.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentFlask Study Notes
Python · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics