Folder & Package Architecture (Best Practices)
A clean and well-organized folder structure is essential in Spring Boot development. It improves readability, scalability, maintainability, and helps teams collaborate without confusion.
Modern Spring Boot projects use a combination of Layered Architecture + Feature-Based Architecture, which makes the code far easier to understand and scale.
High-Level Project Structure (Standard Layout)
src/
├── main/
│ ├── java/
│ │ └── com.example.project/
│ │ ├── controller/
│ │ ├── service/
│ │ ├── repository/
│ │ ├── model/ (or entity/)
│ │ ├── dto/
│ │ ├── mapper/
│ │ ├── config/
│ │ ├── exception/
│ │ ├── util/
│ │ └── ProjectApplication.java
│ └── resources/
│ ├── application.yml / application.properties
│ ├── static/ (CSS, JS, images)
│ ├── templates/ (Thymeleaf, Freemarker)
│ ├── db/migration (Flyway/Liquibase)
│ ├── messages.properties
│ └── logback-spring.xml
└── test/
└── java/
This layout gives a clear idea of where controllers, services, repositories, configurations, and resources belong.
Layered Architecture Package Structure (Small–Medium Projects)
com.example.project
├── controller → Handles API requests (REST endpoints)
├── service → Business logic
├── repository → Database access layer (JPA, JDBC)
├── model/entity → Domain entities mapped to DB tables
├── dto → Request/Response classes
├── mapper → Entity ↔ DTO converters
├── config → App-wide configurations
├── exception → Custom exceptions + global handlers
├── util → Utility/helper classes
└── security → JWT, filters, authentication
Why layered architecture?
- Clean separation of concerns
- Easy unit testing
- Good for beginners
- Works well in small to medium codebases
Feature-Based Package Structure (Best for Large & Enterprise Projects)
This is the modern recommended structure used by large teams and microservices.
com.example.project/
└── user/
├── UserController
├── UserService
├── UserRepository
├── UserEntity
├── UserDTO
├── UserMapper
└── UserException
└── product/
└── order/
└── auth/
└── common/
├── config/
├── exception/
Why feature-based is better?
-
Everything for one module stays together
- No jumping between folders
- Ideal for microservice-ready architecture
- Makes onboarding new developers easier
- Scales smoothly as features grow
Industry-standard projects (Uber, Netflix, Amazon microservices) follow this.
Hybrid Architecture (Most Popular in 2025)
Combines both layered + feature-based approaches:
com.example.project/
├── common/
│ ├── config/
│ ├── exception/
│ └── util/
└── features/
├── user/
├── product/
├── order/
└── auth/
This structure gives clean architecture, high modularity, and maximum scalability.
What Goes Where?
| Component | Purpose | Folder |
|---|---|---|
| Controller | Handles HTTP requests/responses | controller/ or feature/controller/ |
| Service | Business logic | service/ |
| Repository | Database operations | repository/ |
| Entity | JPA models mapped to tables | entity/ or model/ |
| DTO | Request/response objects | dto/ |
| Mapper | Converts Entity ↔ DTO | mapper/ |
| Config | Beans, security, CORS, Swagger | config/ |
| Exception | Custom exceptions & handlers | exception/ |
| Util | Helper classes | util/ |
Resources Folder Structure (Backend Essentials)
resources/
├── application.yml
├── static/ → CSS, JS, images
├── templates/ → HTML templates
├── db/migration/ → Flyway/Liquibase scripts
├── messages.properties
└── logback-spring.xml
Naming Conventions (Industry-Level Standard)
Packages → lowercase
com.example.project.controller
Classes → PascalCase
UserController, ProductService
Interfaces → PascalCase
UserRepository
Beans → camelCase
userService, jwtTokenProvider
Properties → kebab-case
spring.datasource.url
Diagram
Client Request
↓
Controller (Handles API calls)
↓
Service (Business Logic)
↓
Repository (Database Access)
↓
Database
↑
Entity / DTO / Mapper
↑
Config / Exception / Util
Conclusion
A well-designed Folder & Package Architecture is crucial for building high-quality Spring Boot applications. It ensures:
- Clear separation of concerns
- Easier debugging and testing
- Faster development
- Better scalability
- Clean code for teams and enterprise apps
Layered Architecture is perfect for beginners and small apps, while Feature-Based or Hybrid Architecture is best for modern, scalable, production-grade applications.