Spring Modulith

Spring Modulith is a Spring project that helps developers build well-structured, modular Spring Boot applications.

Spring Modulith provides tools and best practices for creating domain-driven, modular monoliths. This approach simplifies the development of large, complex applications without the adoption of microservices architecture from the start of development.

Enable Spring Modulith support in IntelliJ IDEA

The Spring Modulith plugin is bundled and enabled by default in IntelliJ IDEA Ultimate. This functionality is not available in IntelliJ IDEA Community Edition and IntelliJ IDEA Edu.

Spring Modulith support becomes available the moment you add the dependency to your project. To ensure that the plugin is enabled:

Press Ctrl+Alt+S to open settings and then select Plugins.
Open the Installed tab, search for Spring Modulith, and make sure that the checkbox next to the plugin is selected.

Spring Modulith plugin bundled and enabled

Structure of a modular application

A Spring Modulith application usually consists of:

A main package with a class that is used to run the application. This class is annotated with @SpringBootApplication and usually has the main(…) method used to run it.
Application modules — direct sub-packages of the main package that have:
- Provided interface: an API made available to other modules, typically implemented using Spring beans and domain events published by the module.
- Internal implementation components: intended for internal use within the module, not accessible from outside.
- Required interface: a module's use of other modules' features, like calling their Spring beans, listening to their events, or using their exposed configuration properties.

Here is an example arrangement of a simple application:

             Demo
             ╰─ src/main/java
                 ╰─ bookstore                           // main package
                    ╰─ BookstoreMainApplication.java
                    ╰─ catalog                          // application module package
                        ╰─ ProductApi.java              // provided interface
                        ╰─ domain
                            ╰─ ProductService.java      // internal component
                    ╰─ common
                    ╰─ orders
                        ╰─ web
                            ╰─ OrderRestController.java // ProductApi is required interface
                    ╰─ config
         

OrderRestController.java from the orders module here has a dependency on the exposed ProductApi.java from the catalog module.

In IntelliJ IDEA, as soon as you open the Project tool window Alt+1, you can review the structure of your modular application and navigate between its parts.

In the picture below, there is a modular application with top-level modules marked by a green lock and internal components marked by a red lock.

Also, you can inspect the logical structure of the application from the framework's point of view: select the main application class that is annotated with @SpringBootApplication and press Alt+7 (or go to View | Tool Windows | Structure in the main menu).

List of the application's modules in the Structure tool window

The Modulith-specific Modules node shows the list of application's modules, their IDs, allowed dependencies, and named interfaces.

Apply the Spring Modulith's guidelines

IntelliJ IDEA helps maintain your application's structure in line with Spring Modulith's architectural principles by providing a set of inspections and quick-fixes. By default, these inspections have the severity level of an error, but the highlighted code does not cause neither compilation nor runtime errors. These issues will fail Modulith-specific tests only.

When implementing an application with Spring, developers may need to inject various Spring beans into other beans. IntelliJ IDEA helps with this by providing a bean autocompletion feature.

For Spring Modulith, this feature has been adjusted. If an injection violates the application's module boundaries, you will see the warning icon in the completion popup.

For the existing code, IntelliJ IDEA highlights bean usages that break the Spring Modulith rules and suggests quick-fixes that will refactor your code to align with the modular structure (invoked by clicking or pressing Alt+Enter).

Depending on your architectural guides, you can select from the following quick-fixes:

Move the component from the original module to the base package.
Annotate the injected class with @NamedInterface to open this class for other modules.
Open the module that contains this class.
The quick-fix creates a package-info.java file with the @ApplicationModule annotation for the module that contains the class you want to import. The module is marked as OPEN.

Work with application module dependencies

When we specify intermodule dependencies, IntelliJ IDEA provides name completion and validation for modules, as well as navigation between them.

To add a dependency from one module to others explicitly, we need to modify the package-info.java file in the module that requires the dependency.
For example, to make the orders module depend on the catalog and common modules, we need to modify the package-info.java file located in the orders module.
In the package-info.java file, place the caret inside the quotation marks in allowedDependencies = {""} and press Ctrl+Space or start typing the module's name.
IntelliJ IDEA shows available module dependencies in the completion popup:
- module — a dependency on the entire module.
- module :: interface — a dependency on a specific named interface provided by the module.
- module :: * — a dependency on all interfaces provided by the module.
Select the one you want to add and press Enter.
allowedDependencies = {} acts as an allowlist.
When the braces are empty ({}), no dependencies are allowed. When specific modules are listed, then only those modules are allowed to be used.
You can navigate to an added module by clicking it and pressing Ctrl+B.
The module gets selected in the Project tool window Alt+1.
If a module listed as a dependency does not exist, IntelliJ IDEA will highlight the reference, allowing you to fix the application's structure to prevent a startup failure.

20 August 2025