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.