{"id":683448,"date":"2026-02-25T13:40:36","date_gmt":"2026-02-25T12:40:36","guid":{"rendered":"https:\/\/blog.jetbrains.com\/?post_type=idea&p=683448"},"modified":"2026-03-03T13:55:02","modified_gmt":"2026-03-03T12:55:02","slug":"migrating-to-modular-monolith-using-spring-modulith-and-intellij-idea","status":"publish","type":"idea","link":"https:\/\/blog.jetbrains.com\/ko\/idea\/2026\/02\/migrating-to-modular-monolith-using-spring-modulith-and-intellij-idea","title":{"rendered":"Migrating to Modular Monolith using Spring Modulith and IntelliJ IDEA"},"content":{"rendered":"\n

As applications grow in complexity, maintaining a clean architecture becomes increasingly challenging. The traditional package-by-layer<\/strong> approach of organizing code into controllers<\/em>, services<\/em>, repositories<\/em>, and entities<\/em> packages often leads to tightly coupled code that’s hard to maintain and evolve.<\/p>\n\n\n\n

Spring Modulith, combined with IntelliJ IDEA’s excellent tooling support, offers a powerful solution for building well-structured modular monoliths.<\/p>\n\n\n\n

In this article, we will use a bookstore sample application<\/a> as an example to demonstrate Spring Modulith features.<\/p>\n\n\n\n

\n

If you are interested in building a Modular Monolith using Spring and Kotlin, check out Building Modular Monoliths With Kotlin and Spring<\/a><\/p>\n<\/blockquote>\n\n\n\n

1. The Problem with Monoliths and Package-by-Layer<\/h2>\n\n\n\n

Many Spring Boot applications are organized by technical layer<\/strong> rather than by business capability. A typical layout looks like this:<\/p>\n\n\n\n

bookstore\n  |-- config\n  |-- entities\n  |-- exceptions\n  |-- models\n  |-- repositories\n  |-- services\n  |-- web<\/pre>\n\n\n\n
This package-by-layer<\/strong> style causes several problems.<\/p>\n\n\n\n
The Code Structure Doesn\u2019t Express What the Application Does<\/h3>\n\n\n\n
When you open the project, you see \u201crepositories,\u201d \u201cservices,\u201d and \u201cweb,\u201d but not \u201ccatalog,\u201d \u201corders,\u201d or \u201cinventory.\u201d The domain is hidden behind technical folders, which makes it harder for developers to find feature-related code and understand boundaries.<\/p>\n\n\n\n
Everything Tends to Become Public<\/h3>\n\n\n\n
In a layer-based layout, types in one package are often used from many others. To allow that, classes are made public<\/strong>, which effectively exposes them to the whole application. There is no clear \u201cpublic API\u201d per feature, and hence anything can depend on anything.<\/p>\n\n\n\n
Tight Coupling and Spaghetti Code<\/h3>\n\n\n\n
With no explicit boundaries, services and controllers from different features depend on each other\u2019s internals. For example, order logic might call catalog\u2019s ProductService<\/em> directly or reuse internal DTOs. Over time this turns into a tightly coupled \u201cbig ball of mud\u201d<\/strong> where changing one feature risks breaking others.<\/p>\n\n\n\n
Fragile Changes<\/h3>\n\n\n\n
Adding or changing a feature often forces you to touch code in repositories<\/em>, services<\/em>, and web<\/em> at once, with no clear \u201cmodule\u201d to test or reason about. Refactoring becomes risky because the impact is hard to see.

In short:<\/strong> package-by-layer encourages a single, undivided monolith with weak boundaries and unclear ownership. Spring Modulith addresses this by turning your codebase into an explicit set of modules<\/strong> with clear APIs and enforced boundaries.<\/p>\n\n\n\n
2. What Benefits Spring Modulith Brings<\/h2>\n\n\n\n
Spring Modulith<\/a> helps you build modular monoliths<\/strong>: one deployable application, but with clear, domain-driven modules and enforced structure.<\/p>\n\n\n\n
Explicit Module Boundaries<\/h3>\n\n\n\n
Modules are direct sub-packages<\/strong> of your application\u2019s base package (e.g. com.example.bookstore.catalog<\/code>, com.example.bookstore.orders<\/code>). Spring Modulith treats each as a module and checks that:<\/p>\n\n\n\n