spring-boot-modulith — Claude Code skill: modules and setup
spring-boot-modulith is a Claude Code skill that structures Spring Boot apps as bounded modules connected through events. It supports modular monolith design and module boundary checks.
MIT 1 installs ★ 23 updated 2026-10-16
npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a claude-codeWhat spring-boot-modulith does
The skill maps DDD bounded contexts to application packages. Types in a module's base package form its public API; placing implementation classes under internal keeps them out of other modules. Its guidance targets Spring Boot 4 with Spring Modulith 2.0. Package layout defines the boundaries.
For cross-module communication, it recommends events handled with @ApplicationModuleListener instead of injecting another module's beans. The material covers @ApplicationModule configuration, event publishing, ApplicationModules.verify() boundary checks, and sending events to Kafka or AMQP with @Externalized. A JDBC event log provides at-least-once delivery.
Included patterns cover Java and Kotlin event handlers, module verification with PlantUML generation, and Scenario API tests. Direct bean injection across modules cuts across the intended boundaries; use events or a module's exposed API instead.
What it helps with
- map DDD contexts to application packages
- keep implementation types private to each module
- connect modules with
@ApplicationModuleListener - check module boundaries with
ApplicationModules.verify() - externalize events to Kafka or AMQP
Example prompts for the agent
- Organize this Spring Boot app into modules that match its DDD bounded contexts.
- Show how to handle an event from another module with
@ApplicationModuleListener. - Add a test that checks module boundaries using
ApplicationModules.verify().
How to install spring-boot-modulith
1Skills CLI (Vercel)
npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a claude-code2Manually: put the files in place
~/.claude/skills/spring-boot-modulith/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/spring-boot-modulith/
1Skills CLI (Vercel)
npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a codex2Manually: put the files in place
.agents/skills/spring-boot-modulith/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a cursor2Manually: put the files in place
.cursor/skills/spring-boot-modulith/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install joaquimscosta/arkhe-claude-plugins plugins/spring-boot/skills/spring-boot-modulith2Manually: put the files in place
.github/skills/spring-boot-modulith/SKILL.md1Skills CLI (Vercel)
npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a gemini-cli2Platform CLI
gemini skills install https://github.com/joaquimscosta/arkhe-claude-plugins --path plugins/spring-boot/skills/spring-boot-modulithManually: put the files in place
.devin/skills/spring-boot-modulith/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about spring-boot-modulith
How do I install spring-boot-modulith in Claude Code?
Run npx skills add joaquimscosta/arkhe-claude-plugins --skill spring-boot-modulith -a claude-code. The skill file is placed at ~/.claude/skills/spring-boot-modulith/SKILL.md.
What does spring-boot-modulith do?
It guides you through organizing a Spring Boot 4 modular monolith, defining package-based boundaries, communicating through events, and checking module dependencies.
How should modules communicate with this skill?
Use events with @ApplicationModuleListener or expose a module API. Directly injecting beans across module boundaries is listed as an anti-pattern.
Source text
SKILL.md · MIT
--- name: spring-boot-modulith description: Spring Modulith 2.0 implementation for bounded contexts in Spring Boot 4. Use when structuring application modules, implementing @ApplicationModuleListener for event-driven communication, testing with Scenario API, enforcing module boundaries, externalizing events to Kafka/AMQP, building a modular monolith, defining module dependencies, managing inter-module events, or organizing DDD modules as packages. Covers package-based module boundaries, named interfaces, event publication, and Scenario API testing. For architecture decisions, see domain-driven-design skill. spring-boot-version: "4.0" --- # Spring Modulith for Bounded Contexts Implements DDD bounded contexts as application modules with enforced boundaries and event-driven communication. ## Core Concepts | Concept | Description | |---------|-------------| | **Application Module** | Package-based boundary = bounded context | | **Module API** | Types in base package (public) | | **Internal** | Types in sub-packages (encapsulated) | | **Events** | Cross-module communication mechanism | ## Module Structure ``` src/main/java/ ├── com.example/ │ └── Application.java ← @SpringBootApplication ├── com.example.order/ ← Module: order │ ├── OrderService.java ← Public API │ ├── OrderCreated.java ← Public event │ ├── package-info.java ← @ApplicationModule config │ └── internal/ ← Encapsulated │ ├── OrderRepository.java │ └── OrderEntity.java ├── com.example.inventory/ ← Module: inventory │ ├── InventoryService.java │ └── internal/ └── com.example.shipping/ ← Module: shipping ``` Types in `com.example.order` = public API Types in `com.example.order.internal` = hidden from other modules ## Quick Patterns See [EXAMPLES.md](EXAMPLES.md) for complete working examples including: - **Module Configuration** with @ApplicationModule - **Event Publishing** with domain event records - **Event Handling** with @ApplicationModuleListener (Java + Kotlin) - **Module Verification Test** with PlantUML generation - **Event Externalization** for Kafka/AMQP ## Spring Boot 4 / Modulith 2.0 Specifics - **@ApplicationModuleListener** combines `@Async` + `@Transactional(REQUIRES_NEW)` + `@TransactionalEventListener(AFTER_COMMIT)` - **Event Externalization** with `@Externalized` annotation for Kafka/AMQP - **JDBC event log** ensures at-least-once delivery ## Detailed References - **Examples**: See [EXAMPLES.md](EXAMPLES.md) for complete working code examples - **Troubleshooting**: See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues and Boot 4 migration - **Workflow**: See [WORKFLOW.md](WORKFLOW.md) for detailed step-by-step Modulith setup - **Module Structure**: See [references/MODULE-STRUCTURE.md](references/MODULE-STRUCTURE.md) for package conventions, named interfaces, dependency rules - **Event Patterns**: See [references/EVENTS.md](references/EVENTS.md) for publishing, handling, externalization, testing with Scenario API ## Related Skills | Need | Skill | |------|-------| | DDD concepts | `domain-driven-design` | | Data layer per module | `spring-boot-data-ddd` | | Module event testing | `spring-boot-testing` | | REST APIs for modules | `spring-boot-web-api` | ## Anti-Pattern Checklist | Anti-Pattern | Fix | |--------------|-----| | Direct bean injection across modules | Use events or expose API | | Synchronous cross-module calls | Use `@ApplicationModuleListener` | | Module dependencies not declared | Add `allowedDependencies` in `@ApplicationModule` | | Missing verification test | Add `ApplicationModules.verify()` test | | Internal types in public API | Move to `.internal` sub-package | | Events without data | Include all data handlers need | ## Critical Reminders 1. **One module = one bounded context** — Mirror DDD boundaries 2. **Events are the integration mechanism** — Not direct method calls 3. **Verify in CI** — `ApplicationModules.verify()` catches boundary violations 4. **Reference by ID** — Never direct object references across modules 5. **Transaction per module** — `@ApplicationModuleListener` ensures isolation
© joaquimscosta · MIT · joaquimscosta/arkhe-claude-plugins