Skip to content

rrezartprebreza/spring-boot-skills / skills/spring-boot-3/spring-modulith

spring-modulith

Verified

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 3 baseline

Use the Spring Modulith 1.4 line with Boot 3.5; check the official compatibility matrix for older Boot 3 minors.

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 and bad cross-module dependency.

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 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

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 implementationStars: 321kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 321kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 321kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 321kUpdated Claude CodeCodexVerifiedInstall