rrezartprebreza/spring-boot-skills / skills/spring-boot-4/spring-modulith
spring-modulith
VerifiedUse when organizing or verifying a modular Spring Boot monolith with Spring Modulith, including module APIs, dependency rules and reliable module events. Do not restructure an application into modules for an unrelated endpoint change.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.4 KB |
| agents/openai.yaml | config | 238 B |
| examples/bad-module-dependency.java | other | 322 B |
| examples/good-module-test.java | other | 332 B |
SKILL.md
View on GitHub---
name: spring-modulith
description: >
Use when organizing or verifying a modular Spring Boot monolith with Spring Modulith, including module APIs, dependency rules and reliable module events. Do not restructure an application into modules for an unrelated endpoint change.
---
# Spring Modulith
## Spring Boot 4 baseline
Use the Spring Modulith 2.x line matching the exact Boot 4 minor; do not import a Boot 3 Modulith 1.x BOM.
## Apply within the existing architecture
Inspect the application root package, module boundaries and current dependency graph.
Use direct subpackages as modules; keep their API at the module root and implementation in
internal subpackages. Expose a named interface only for an intentional shared API.
Use allowedDependencies when the architecture needs explicit dependency constraints.
Avoid creating a generic shared module that every feature depends on.
## Verify boundaries
Add spring-modulith-starter-test with test scope and run
ApplicationModules.of(Application.class).verify() in CI. It checks cycles and access to module
internals. Add ApplicationModuleTest for behavior confined to a module. A passing structure
check does not prove transactional or delivery correctness.
See [good module verification](examples/good-module-test.java) and
[bad cross-module dependency](examples/bad-module-dependency.java).
## Reliable events
Publish immutable event payloads containing IDs and necessary facts, not managed JPA entities.
Use ApplicationModuleListener for asynchronous transactional listeners when that timing fits.
For delivery that must survive a process crash, configure a persistent event publication
registry using the chosen JDBC/JPA starter and manage its schema through migrations.
An in-memory registry and a plain after-commit callback are not durable delivery.
Make handlers idempotent: a crash after the business effect but before recording completion
can cause redelivery. Define retry/republication and retention explicitly, and test failed
listeners and application restarts. For external brokers, use supported event externalization
with persistent publication tracking; do not promise end-to-end exactly-once processing.
## Verification scope
The workflow fixture checks a valid public-API dependency and rejection of an internal
package dependency using real ApplicationModules verification. It uses separate minimal
fixture packages, not the application's Application class; durable event publication,
listener retries and process-restart behavior are not covered.
See the [coverage matrix](https://github.com/rrezartprebreza/spring-boot-skills/blob/main/verification/MATRIX.md)
for pinned versions and remaining gaps.
## Gotchas
- Agent imports a repository from another module's internal package - call its public API or consume an event.
- Agent adds Modulith to a simple unrelated task - preserve the requested scope.
- Agent assumes ApplicationModuleListener alone guarantees durability - configure persistent publication tracking.
- Agent publishes an entity with lazy associations - publish an immutable event contract.
- Agent tests only the happy path - verify cycles, module access and event redelivery.
## Official sources
- [Module verification](https://docs.spring.io/spring-modulith/reference/verification.html)
- [Events and publication registry](https://docs.spring.io/spring-modulith/reference/events.html)
- [Compatibility](https://docs.spring.io/spring-modulith/reference/appendix.html)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |