Create Spring Modulith Skill for Java Plugin

[giuseppe-trisciuoglio]

Create Spring Modulith Skill for Java Plugin

Overview

Implement a new Spring Modulith skill for the Java plugin to provide developers with comprehensive knowledge and patterns for building modular monolithic applications. This skill should enable validation of module boundaries, automatic architecture diagram generation, and best practices for implementing domain-driven modular architectures.

Problem Statement

Many enterprises are transitioning away from microservices back to Modular Monoliths as a more pragmatic architectural approach. However, developers often lack guidance on:

• How to properly structure applications into logical, domain-aligned modules
• Validating and enforcing module boundaries at compile-time and test-time
• Visualizing application architecture and module dependencies
• Implementing event-driven inter-module communication with guaranteed delivery
• Testing individual modules in isolation

This skill will address these gaps by providing practical patterns and automated tooling for Spring Modulith.

Objectives

The skill should deliver:

1. Module Structure Validation

   • Teach how to use ApplicationModules API to analyze and verify module structure
   • Provide patterns for defining module boundaries using package organization
   • Explain module configuration with @Modulith and @ApplicationModule annotations
   • Demonstrate validation of architectural constraints (no cycles, no internal access violations)

2. ArchUnit Integration

   • Show how to integrate ArchUnit for compile-time and test-time module verification
   • Provide reusable ArchUnit rules for enforcing module boundaries
   • Demonstrate hexagonal architecture patterns with driving/driven ports
   • Include examples of package structure following architectural principles

3. Automated Documentation & Diagrams

   • Generate PlantUML architecture diagrams from module structure
   • Create module dependency graphs automatically
   • Document module public APIs and internal components
   • Generate architecture documentation snippets

4. Event-Driven Inter-Module Communication

   • Explain @ApplicationModuleListener for transactional event handling
   • Demonstrate guaranteed event delivery using EventPublicationRegistry
   • Show how to handle incomplete/failed event publications
   • Provide patterns for async communication between modules

5. Module Integration Testing

   • Teach @ApplicationModuleTest for isolated module testing
   • Demonstrate different bootstrap modes (STANDALONE, DIRECT_DEPENDENCIES, ALL_DEPENDENCIES)
   • Show the Scenario DSL for event-driven testing
   • Provide examples of testing module interactions

6. Best Practices & Patterns

   • Modular thinking from application start
   • Domain-aligned module organization
   • Public API design for modules
   • Dependency management and avoiding circular dependencies
   • Module observability with Micrometer at module level

Reference Materials

• Spring Modulith Core Concepts: https://context7.com/spring-projects/spring-modulith/llms.txt

  • ApplicationModules API
  • Module configuration annotations
  • Event publication and listening
  • Integration testing capabilities

• ArchUnit Integration Guide: https://context7.com/clutcher/spring-modulith-module-archunit/llms.txt

  • Setting up ArchUnit tests for module verification
  • Hexagonal architecture package structure
  • Module boundary validation rules
  • Practical testing examples

Skill Content Structure

The skill should include:

1. Foundational Concepts

• What is a Modular Monolith and why it matters
• Comparison with microservices and monolithic architectures
• Benefits of Spring Modulith approach

2. Module Structure & Organization

• Defining modules through package hierarchy
• Module public APIs and internal components
• Module configuration and metadata
• Shared modules and cross-cutting concerns

3. Validation & Verification

• Using ApplicationModules for structure analysis
• ArchUnit rules for boundary enforcement
• Compile-time vs. runtime verification
• Detecting and preventing architectural violations

4. Architecture Documentation

• Generating PlantUML diagrams
• Module dependency visualization
• Architecture documentation generation
• Keeping documentation in sync with code

5. Event-Driven Communication

• Publishing events between modules
• Guaranteed delivery patterns
• Event listener configuration
• Handling failed publications

6. Testing Strategies

• Unit testing within modules
• Integration testing with @ApplicationModuleTest
• Testing module interactions with Scenario
• Different bootstrap modes for different test scenarios

7. Practical Examples

• Complete e-commerce system example
• Order management module
• Inventory management module
• Payment processing module
• Inter-module event flows

8. Common Pitfalls & Solutions

• Circular dependencies between modules
• Leaking internal implementations
• Improper event handling
• Testing isolation issues

Acceptance Criteria

• Skill documentation covers all core Spring Modulith concepts
• Includes practical, runnable code examples for each pattern
• Provides ArchUnit integration examples for module verification
• Demonstrates automatic diagram generation
• Includes best practices for modular architecture design
• Contains complete example application with multiple modules
• Covers event-driven communication patterns
• Provides testing strategies and examples
• Includes troubleshooting guide for common issues
• Documentation is clear, well-organized, and searchable

Implementation Notes

• Focus on practical, production-ready patterns
• Provide copy-paste ready code examples
• Include both simple and advanced scenarios
• Ensure examples work with current Spring Boot and Spring Modulith versions
• Consider different application sizes (small, medium, large)
• Include performance considerations for module verification

Related Issues

This skill complements existing Java plugin skills and provides enterprise-grade architectural guidance for building maintainable, scalable applications.

Labels

• enhancement
• skill
• java
• spring-modulith
• architecture
• pattern