Spring Boot Project Structure Explained: Folders, Files, and How They Connect
This is Part 2 of my Spring Boot series. In Part 1, I explained what Spring Boot is and why we use it. Now let's open a real project and understand what is inside.
When you create a Spring Boot project, you get many files and folders. It looks confusing at first. This post answers three simple questions:
- What are all these files?
- Where do I write my code?
- How do my classes work together? Step 1: What you get in a new project
At the start, you only work with three things:
What
Why
pom.xml
Add libraries here. Example: you need a database, so you add a database library.
src/main/java
Your Java code goes here.
application.properties
Your settings go here (port, database password, and so on).
Everything else, you can ignore for now.
Step 2: The start button
Open DemoApplication.java:
@SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } } When you run this class, your whole application starts. The annotation @SpringBootApplication tells Spring: start here, and look for my other classes.
There is one important rule. Spring only looks inside the package of this class, and below it.
com.example.demo <- DemoApplication is here
├── controller/ OK, Spring finds it
├── service/ OK, Spring finds it
└── repository/ OK, Spring finds it
com.other.stuff NOT OK, Spring never looks here
If you put a class outside this package, Spring ignores it and you get strange errors.
Step 3: The four layers
To keep code clean, we split it into layers. Think of a restaurant:
The waiter does not cook. The chef does not go to the storeroom himself. Each layer talks only to the next one.
User -> Controller -> Service -> Repository -> Database
In your project, each layer is a package (a folder):
com.example.demo
├── controller/
├── service/
├── repository/
└── entity/
Step 4: Follow one request
Let's say a user opens this URL to get all customers:
GET http://localhost:8080/api/v1/customer/get-all-customers
Here is what happens, step by step.
- The controller receives the request. It calls the service.
@RestController @RequestMapping("/api/v1/customer") public class CustomerController { private final CustomerService customerService; public CustomerController(CustomerService customerService) { this.customerService = customerService; } @GetMapping("/get-all-customers") public List<Customer> getAll() { return customerService.getAllCustomers(); } } - The service does the work. It asks the repository for the data.
@Service public class CustomerService { private final CustomerRepository customerRepository; public CustomerService(CustomerRepository customerRepository) { this.customerRepository = customerRepository; } public List<Customer> getAllCustomers() { return customerRepository.findAll(); } } - The repository reads the database. You write almost nothing:
@Repository public interface CustomerRepository extends JpaRepository<Customer, Integer> { } This empty interface already gives you findAll(), save(), findById() and deleteById(). Spring writes the code for you.
- The answer goes back up. Database -> Repository -> Service -> Controller -> the user sees the customers as JSON.
Notice the pattern: the controller has a service, and the service has a repository. That is how the files connect.
Step 5: Who creates these objects?
Look again at the controller. It uses customerService, but we never wrote new CustomerService().
So where does it come from?
Spring creates it for you. Here is how, in plain words:
- When the app starts, Spring looks for classes marked with
@RestController, @Service or @Repository.
It creates one object of each class. These objects are called beans.
When a class needs another one in its constructor, Spring hands it over. This is called dependency injection.
Think of a manager who hires staff. The waiter does not hire the chef. The manager (Spring) gives the waiter a chef when he starts work.
This is why those annotations matter. If you forget @Service, Spring never creates the chef, and your app fails to start with an error like No qualifying bean of type CustomerService.
Step 6: The settings file
application.properties holds your settings. Here is a small example:
server.port=8081 spring.datasource.url=jdbc:mysql://localhost:3306/mydb spring.datasource.username=root spring.datasource.password=your_password You never write code to connect to the database. You only write these lines, and Spring Boot makes the connection for you. (Never upload your real password to GitHub.)
Quick recap
• pom.xml lists your libraries. application.properties holds your settings.
• Your code lives in src/main/java, inside the package of the main class.
• Four layers: Controller -> Service -> Repository -> Database. Each talks only to the next one.
• Spring creates the objects and gives them to each other. You just write the constructor.
What's next
In Part 3 we will build a real REST API step by step and test it with Postman. If this post helped you, leave a comment and tell me what is still unclear. I will explain it better in the next post.




