📦 Industry-Wide Folder & Packaging Structures in Spring Boot

Spring Boot is one of the most popular Java frameworks for building scalable web applications. But writing good code isn’t enough—structuring your project properly is equally crucial. The right folder/package structure:

• Enhances code readability and maintainability
• Helps teams scale and collaborate
• Aligns with domain modeling and microservices architecture

In this blog, we’ll explore the most commonly adopted folder structures across the industry, with examples, pros & cons, and when to use what.

🧱 1. Standard Layered Architecture

👤 Best For: Monoliths, small-to-mid web apps

This is the most traditional structure used by most teams starting with Spring Boot.

com.example.myapp
├── controller         // REST Controllers
├── service            // Business logic
├── repository         // Spring Data Repositories
├── model              // JPA Entities or POJOs
├── dto                // Request/Response DTOs
├── config             // Spring Boot Configs
├── exception          // Custom exceptions, handlers
├── mapper             // MapStruct or manual mappers
└── MyAppApplication.java

✅ Pros

• Easy to learn and organize
• Aligned with typical 3-tier architecture

❌ Cons

• Can get bloated in large projects
• Tightly couples layers

🧠 Example

@RestController
@RequestMapping("/users")
public class UserController {
    private final UserService userService;
    @GetMapping("/{id}")
    public UserDto getUser(@PathVariable Long id) {
        return userService.getUserById(id);
    }
}

🧩 2. Feature-Based Modular Structure (Vertical Slice)

🚀 Best For: Medium to large modular apps

Organized by feature instead of layers. Ideal when teams work on distinct modules.

com.example.myapp
├── features
│   ├── user
│   │   ├── controller
│   │   ├── service
│   │   ├── repository
│   │   ├── dto
│   │   ├── model
│   │   └── mapper
│   └── product
│       ├── controller
│       ├── service
│       ├── repository
│       └── dto
├── config
├── exception
└── MyAppApplication.java

✅ Pros

• Scales well with multiple teams
• Each feature is self-contained

❌ Cons

• Slight learning curve
• Shared logic must be carefully managed

🧱 3. Hexagonal Architecture (Ports & Adapters / Clean Architecture)

🏛️ Best For: Domain-Driven, long-lived enterprise systems

Separates domain, application logic, and infrastructure clearly.

com.example.myapp
├── domain
│   ├── model
│   └── service
├── application
│   └── usecases
├── infrastructure
│   ├── persistence
│   └── rest
├── web
│   └── controller
├── config
└── MyAppApplication.java

✅ Pros

• Testable and decoupled
• Clean separation of concerns

❌ Cons

• More boilerplate and upfront design
• Not suited for trivial apps

🔌 Example:

public interface UserRepository {
    Optional<User> findById(Long id);
}

Implemented by an adapter in infrastructure.persistence.

🧳 4. Multi-Module Maven Structure

🧬 Best For: Microservices, shared modules

Each feature is an independent module, often maintained in different repos.

project-root/
├── common/                   // Shared DTOs, utils
│   └── src/main/java/...
├── user-service/
│   └── src/main/java/com/example/user
├── product-service/
│   └── src/main/java/com/example/product
└── pom.xml                   // Parent POM

✅ Pros

• Clear modular boundaries
• Reusable components

❌ Cons

• Maven complexity
• Shared versioning can be tricky

🌊 5. Reactive Structure (WebFlux / Handler-Based)

⚛️ Best For: Reactive, async applications

Uses functional routing over MVC annotations.

com.example.myapp
├── handler             // Functional endpoint handlers
├── router              // RouterFunction configs
├── service
├── repository
├── model
└── MyAppApplication.java

Example Router

@Bean
public RouterFunction<ServerResponse> route(UserHandler handler) {
    return RouterFunctions
           .route(GET("/users/{id}"), handler::getUser);
}

✅ Pros

• Non-blocking, high throughput
• Lightweight functional style

❌ Cons

• Functional style is less familiar
• Debugging stack traces is harder

⚔️ 6. CQRS-Oriented Structure

🧠 Best For: High-scale systems, Event Sourcing

Separates read and write logic.

com.example.myapp
├── command
│   ├── handler
│   ├── service
│   ├── controller
├── query
│   ├── service
│   ├── controller
├── events
│   └── listeners
└── MyAppApplication.java

✅ Pros

• Optimized for scale
• Clear boundaries

❌ Cons

• Higher complexity
• Eventual consistency challenges

🕸️ 7. GraphQL-Driven Structure

🔍 Best For: GraphQL-first APIs

com.example.myapp
├── graphql
│   ├── resolver
│   ├── schema
│   ├── dto
│   └── service
├── repository
└── MyAppApplication.java

✅ Pros

• Logical schema-based grouping
• Supports GraphQL-first development

❌ Cons

• Requires GraphQL learning
• Less RESTful structure

📊 Comparison Table

🛠️ Which Structure Should You Use?

📁 Final Thoughts

There’s no one-size-fits-all. The right structure depends on your:

• Team size
• Codebase complexity
• Domain modeling
• Delivery expectations

Start simple, and evolve your structure as the system grows.

🧰 Bonus: Generate Feature Skeleton with Spring Boot CLI

spring init --dependencies=web,data-jpa --build=maven --package-name=com.example.user user-service

Want a GitHub Starter Template?

👉 Drop a comment or message, and I’ll share a starter repo matching your preferred structure—layered, modular, reactive, or clean architecture.