305-frameworks-spring-boot-modulith

name: 305-frameworks-spring-boot-modulith description: Use when you need to design, review, or improve modular monoliths with Spring Modulith in Spring Boot applications - including application module package structure, ApplicationModules verification, named interfaces, allowed dependencies, domain events, @ApplicationModuleTest, Scenario-based module tests, generated documentation, actuator exposure, observability, and event publication registry choices. This should trigger for requests such as Add Spring Modulith to a Spring Boot application; Review Spring Modulith module boundaries; Improve modular monolith architecture in Spring Boot; Add @ApplicationModuleTest tests; Generate Spring Modulith documentation. Part of cursor-rules-java project license: Apache-2.0 metadata: author: Juan Antonio Breña Moral version: 0.16.0

Spring Boot - Spring Modulith

Apply Spring Modulith guidelines for Spring Boot modular monoliths.

What is covered in this Skill?

• Spring Modulith BOM and starter dependency selection
• Business-capability package structure for application modules
• ApplicationModules verification and architecture tests
• Named interfaces and explicit allowed dependencies
• Domain events for loose coupling between modules
• @ApplicationModuleTest and Scenario-based module integration tests
• Generated module documentation, actuator exposure, and observability
• Event publication registry choices for reliable domain events

Scope: Apply recommendations based on the reference rules, official Spring Modulith documentation, and good/bad examples.

Constraints

Before applying Spring Modulith changes, ensure the project compiles. After improvements, run full verification including module structure tests.

• MANDATORY: Run ./mvnw compile or mvn compile before applying any change
• PRECONDITION: The project must be a Spring Boot application; for non-Boot Java modularity use architecture or design skills instead
• BASELINE: Align dependency choices with Spring Boot 4.0.x and the Spring Modulith compatibility matrix
• SAFETY: If compilation fails, stop immediately
• VERIFY: Run ./mvnw clean verify or mvn clean verify after applying improvements
• BEFORE APPLYING: Read the reference for detailed rules, good/bad patterns, and official documentation links

When to use this skill

• Add Spring Modulith to a Spring Boot application
• Review Spring Modulith module boundaries
• Improve modular monolith architecture in Spring Boot
• Add @ApplicationModuleTest tests
• Generate Spring Modulith documentation
• Refactor Spring Boot modules with Spring Modulith

Workflow

1. Read reference and inspect project structure

Read references/305-frameworks-spring-boot-modulith.md and inspect the Spring Boot version, Maven dependencies, main application package, and current package/module boundaries.

2. Model application modules

Identify business-capability modules, public APIs, internal packages, named interfaces, and intentional allowed dependencies.

3. Apply framework-aligned changes

Add or refine Spring Modulith dependencies, package annotations, architecture verification tests, domain events, and module tests following the reference patterns.

4. Run verification and report results

Execute appropriate build/tests, especially ApplicationModules.verify() and @ApplicationModuleTest coverage, then summarize changes, risks, and follow-up module design work.

Reference

For detailed guidance, examples, and constraints, see references/305-frameworks-spring-boot-modulith.md.