Spring Boot Project Structure and Package Layout That Scales
Lay out a Spring Boot project so component scanning finds your beans, packages follow features, and the structure survives growth from one team to several.

Structure decides how fast a new developer finds things, and how painful the second year of a codebase is. Spring Boot does not impose a layout, but its scanning rules constrain the choices, and Spring Boot 4 keeps the rules that earlier versions had. What follows is the layout we start new services with, and the reasons it holds up when the team grows from two people to ten.
The rule that matters: scanning starts at the main class
dev/javahacks/shop/ShopApplication.java <- @SpringBootApplication
dev/javahacks/shop/orders/...
dev/javahacks/shop/billing/...
dev/javahacks/other/Mailer.java <- not scanned@SpringBootApplication includes @ComponentScan rooted at its own package. A @Service in dev.javahacks.other is silently ignored, and the symptom shows up later as a no qualifying bean error far from the cause. Either move the class under the root package or add scanBasePackages to the annotation. The second option works and is a smell: a main class that has to be told where the code is usually sits in the wrong package.
Never put the main class in the default package, meaning no package statement at all. Scanning would then start at the classpath root and walk every class in every jar, startup slows, and Spring prints a warning saying so. The same applies to a test class without a package, which is how the problem often arrives.
Layout by layer
shop/controller/OrderController
shop/service/OrderService
shop/repository/OrderRepository
shop/model/OrderThis is the shape most tutorials teach, and it is not wrong for a prototype. It is easy to explain, and a newcomer finds the controllers in one folder. The cost appears with the fifth feature. Adding "refunds" means opening four packages, each one now holds a mix of unrelated classes, and because service and repository classes must be public so other packages can reach them, nothing stops a controller in billing from calling the order repository directly. The compiler has no opinion, so the boundaries live in people's heads, and they last as long as the people do.
Layout by feature
shop/orders/OrderController
shop/orders/OrderService
shop/orders/OrderRepository
shop/orders/Order
shop/billing/InvoiceController
shop/billing/InvoiceServiceEverything about orders lives in one package. The repository and most of the service can be package-private, so the rest of the application reaches orders through one deliberate public type, typically the service or a small facade. That is the main reason we prefer it: Java's visibility rules start enforcing the design for free. Deleting a feature also becomes a directory delete. Organizing packages by feature explains the trade in detail, and Spring Modulith turns the idea into a rule the build checks.
The honest cost is duplication of shape. Every feature has the same four files, and a reader who wants every controller must search. IDEs handle that fine, and we accept it.
Where configuration and shared code go
shop/config/SecurityConfig, JacksonConfig, WebConfig
shop/common/Money, Ids, ClockProviderconfig holds cross-cutting wiring: security, serialization, web settings. Keep common small and boring, with value types and tiny helpers that no feature owns. A common package that grows to hold half the code is a layer you invented by another name. When two features need the same class, ask first whether one of them should own it and expose it deliberately. A Money type is shared on purpose, while a CustomerHelper that two features call usually means a missing feature.
Resources and tests
src/main/resources/application.yaml
src/main/resources/application-prod.yaml
src/main/resources/db/migration/V1__create_orders.sql
src/main/resources/static/
src/main/resources/templates/Profile files sit beside the main one. Flyway looks in db/migration by default, so a migration placed anywhere else is never applied and the schema fails to match the entities. Tests mirror the main package names so a test can reach package-private classes without widening their visibility. A test in shop.orders can instantiate the package-private OrderRepository fake it needs, and a test in a differently named package cannot.
Check the structure with a test
Discipline fades, so write the rule down as a test. With ArchUnit:
@Test
void billingDoesNotReachIntoOrders() {
noClasses().that().resideInAPackage("..billing..")
.should().dependOnClassesThat().resideInAPackage("..orders.internal..")
.check(new ClassFileImporter().importPackages("dev.javahacks.shop"));
}This one asks for an internal sub-package inside each feature, where implementation classes go, with only the feature's public types in the parent. The test fails the build when someone imports across the line, which is a far cheaper moment to find out than a code review three weeks later. See enforcing module boundaries for the full setup, including Modulith's ApplicationModules.verify().
A migration path from layers
Moving an existing layered project to features does not need a freeze. Pick the feature with the most churn and move its four classes into a new package in one commit, with an IDE refactoring so imports update. Leave the rest. After the first move, make the old packages package-private where possible and watch which classes the compiler now rejects: those are the hidden dependencies. Repeat per feature, one pull request each. We have seen teams try to do it all at once and abandon it after a week of merge conflicts.
Naming inside a feature package
Once packages follow features, class names can be shorter, since the package already says "orders". We name the entry point after what callers do with it, OrderService or Orders, and the persistence type OrderRepository. A feature package with an internal sub-package holds mappers, specifications and anything else callers should never import. Records for request and response bodies sit next to the controller, because they change with it.
Keep an eye on package size. When one feature package passes about twenty classes, it is usually two features that have not been split yet, such as orders and fulfillment. Splitting is cheap while the types are still package-private, and painful once other features import half of them, so look at the package listing at every release and not only when it hurts.
Keeping the main class small
The class with @SpringBootApplication should do one thing, start the application. Resist adding beans, @EnableScheduling and @EnableAsync there, because the annotations on the main class apply to every test slice that picks it up, and a slice test such as @WebMvcTest then drags in scheduling and async configuration it did not ask for. Put each @Enable... on the small configuration class that needs it, in the config package. The main class stays three lines, and slice tests stay fast and predictable.
Where this does not apply
A small service with one feature does not need sub-packages, and a layer layout is fine for a prototype that will be thrown away. The cost shows up at five or six features, and by then moving is a project of its own, so decide earlier than feels necessary. Spring's scanning rules are in the Spring Boot reference on structuring code, and the Spring Framework reference covers scanning itself. Start with the guide for the full picture.


