spring-boot4-skill 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-02-21
+
+### Added
+
+- **Publish:** `.npmignore` for explicit control of published files (no gitignore fallback warning).
+
+[1.6.0]: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework/compare/v1.5.0...v1.6.0
+
+## [1.5.0] - 2026-02-21
+
+### Added
+
+- **Skill:** New references `architecture-patterns.md` (hexagonal, Vertical Slice, DDD mapping to Modulith, CQRS) and `microservices-architecture.md` (microservices vs Modulith, service boundaries, inter-service communication, API Gateway, distributed observability).
+- **Skill:** spring-modulith.md new section 10 "DDD & Modulith" (aggregate, domain repository, domain vs application events).
+- **Skill:** SKILL.md and README: reference table and Quick decision mermaid updated for architecture and microservices.
+
+[1.5.0]: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework/compare/v1.4.0...v1.5.0
+
 ## [1.4.0] - 2026-02-21
 
 ### Added

package/README.md

@@ -140,7 +140,9 @@ Once installed, Claude Code acts as a **Senior Spring Boot 4 architect**:
 | `skills/java-spring-framework/references/spring-data-mongodb.md` | MongoDB, document DB, Spring Data MongoDB |
 | `skills/java-spring-framework/references/spring-messaging.md` | Kafka, event-driven, @KafkaListener, producer/consumer |
 | `skills/java-spring-framework/references/spring-graphql.md` | GraphQL API, Spring for GraphQL |
-| `skills/java-spring-framework/references/spring-modulith.md` | Module structure, events, integration testing, common pitfalls |
+| `skills/java-spring-framework/references/spring-modulith.md` | Module structure, events, integration testing, common pitfalls, DDD & Modulith |
+| `skills/java-spring-framework/references/architecture-patterns.md` | DDD, hexagonal, Vertical Slice, CQRS, ports & adapters |
+| `skills/java-spring-framework/references/microservices-architecture.md` | Microservices: boundaries, communication, API Gateway, distributed observability |
 | `skills/java-spring-framework/references/build-templates.md` | Complete Gradle KTS + Maven POM templates |
 | `skills/java-spring-framework/references/troubleshooting-migration.md` | Common errors (javax/jakarta, RestTemplate), Boot 3→4 checklist |
 
@@ -162,10 +164,24 @@ Once installed, Claude Code acts as a **Senior Spring Boot 4 architect**:
 
 ## Publishing to npm
 
-```bash
-npm login
-npm publish --access public
-```
+When releasing a new version:
+
+1. **Bump version** in `package.json` (e.g. `1.5.0` → `1.6.0`).
+2. **Update CHANGELOG.md** — add an entry under the new version (Added / Changed / Fixed).
+3. **Commit, tag and push:**
+   ```bash
+   git add .
+   git commit -m "chore: release v1.x.0"
+   git tag v1.x.0
+   git push origin main
+   git push origin v1.x.0
+   ```
+   (Or push all tags at once: `git push origin main && git push --tags`.)
+4. **Publish to npm** (requires npm login and 2FA if enabled):
+   ```bash
+   npm login
+   npm publish --access public
+   ```
 
 After publishing, developers can use:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spring-boot4-skill",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Interactive CLI scaffold for Java 25 / Spring Boot 4.x projects — with a bundled Claude Code skill for AI-assisted development.",
   "type": "module",
   "bin": {

package/skills/java-spring-framework/SKILL.md

@@ -29,7 +29,11 @@ idiomatic for **2026 standards**: Spring Boot 4.0.x, Spring Framework 7.0.x, Jav
 
 ```mermaid
 flowchart TD
-    A[User request] --> B{REST blocking or reactive?}
+    A[User request] --> W{Architecture / DDD / hexagonal / VSA?}
+    W -->|Yes| X[architecture-patterns.md]
+    A --> Y{Microservices design?}
+    Y -->|Yes| Z[microservices-architecture.md]
+    A --> B{REST blocking or reactive?}
     B -->|Blocking MVC + JDBC/JPA| C[spring-boot-4.md + spring-framework-7.md]
     B -->|Reactive WebFlux + R2DBC| D[spring-boot-4.md Reactive section + spring-framework-7.md]
     A --> E{Modular monolith?}
@@ -93,6 +97,8 @@ Load these as needed — do not load all at once:
 | MongoDB | `references/spring-data-mongodb.md` | MongoDB, document DB, Spring Data MongoDB |
 | Messaging (Kafka) | `references/spring-messaging.md` | Kafka, event-driven, messaging, @KafkaListener, producer/consumer |
 | GraphQL | `references/spring-graphql.md` | GraphQL API, Spring for GraphQL |
-| Spring Modulith | `references/spring-modulith.md` | Domain-driven module design, event-driven architecture |
+| Spring Modulith | `references/spring-modulith.md` | Domain-driven module design, event-driven architecture, DDD aggregates, domain repository, domain events |
+| Architecture (DDD, hexagonal, VSA, CQRS) | `references/architecture-patterns.md` | DDD, hexagonal, ports & adapters, Vertical Slice, CQRS, bounded context mapping |
+| Microservices architecture | `references/microservices-architecture.md` | Microservices design, service boundaries, inter-service communication, API Gateway, distributed tracing |
 | Build templates | `references/build-templates.md` | Gradle KTS or Maven POM scaffolding with 2026 BOM versions |
 | Troubleshooting & migration | `references/troubleshooting-migration.md` | Migration from Boot 3, compile/runtime errors (javax/jakarta, RestTemplate, native, null-safety) |

package/skills/java-spring-framework/references/architecture-patterns.md

@@ -0,0 +1,156 @@
+# Application Architecture Patterns — Spring Boot 4
+
+**Spring Boot**: 4.0.x | Application architecture | **Jakarta EE**: 11
+
+This reference covers hexagonal (ports & adapters), Vertical Slice Architecture, DDD mapping to Modulith, and optional CQRS. For module structure and event-driven communication, see `references/spring-modulith.md`. For Kafka messaging, see `references/spring-messaging.md`.
+
+---
+
+## Table of Contents
+
+1. [Hexagonal (Ports & Adapters) with Spring](#1-hexagonal-ports--adapters-with-spring)
+2. [Vertical Slice Architecture](#2-vertical-slice-architecture)
+3. [DDD Mapping to Modulith](#3-ddd-mapping-to-modulith)
+4. [CQRS (Optional)](#4-cqrs-optional)
+
+---
+
+## 1. Hexagonal (Ports & Adapters) with Spring
+
+**Ports** are interfaces that define what the application needs (inbound: use cases; outbound: persistence, messaging, external APIs). **Adapters** are concrete implementations that plug into those ports: REST controllers, JPA/JdbcClient repositories, Kafka listeners.
+
+The domain and use cases stay in the center with no framework dependencies; Spring only appears in adapter classes and `@Bean` configuration.
+
+**Conceptual layout:**
+
+```mermaid
+flowchart LR
+    subgraph adaptersIn [Driving Adapters]
+        REST[REST Controller]
+    end
+    subgraph ports [Ports]
+        UseCase[PlaceOrderPort]
+    end
+    subgraph domain [Domain]
+        Order[Order aggregate]
+    end
+    subgraph adaptersOut [Driven Adapters]
+        Repo[OrderRepository impl]
+        Events[EventPublisher]
+    end
+    REST --> UseCase
+    UseCase --> Order
+    UseCase --> Repo
+    UseCase --> Events
+```
+
+**Port (interface):**
+
+```java
+package com.example.shop.orders.application;
+
+import com.example.shop.orders.domain.Order;
+
+public interface PlaceOrderPort {
+    Order placeOrder(PlaceOrderCommand command);
+}
+```
+
+**Use case (implements or uses the port from the “inside”):**
+
+```java
+package com.example.shop.orders.application;
+
+import com.example.shop.orders.domain.Order;
+import org.springframework.stereotype.Service;
+
+@Service
+public class PlaceOrderUseCase implements PlaceOrderPort {
+
+    private final OrderRepository orderRepository;
+    private final ApplicationEventPublisher events;
+
+    public PlaceOrderUseCase(OrderRepository orderRepository, ApplicationEventPublisher events) {
+        this.orderRepository = orderRepository;
+        this.events = events;
+    }
+
+    @Override
+    public Order placeOrder(PlaceOrderCommand command) {
+        Order order = Order.create(command.sku(), command.quantity());
+        orderRepository.save(order);
+        events.publishEvent(new OrderPlacedEvent(order.id(), order.sku(), order.quantity()));
+        return order;
+    }
+}
+```
+
+**Driven port (repository):**
+
+```java
+package com.example.shop.orders.domain;
+
+public interface OrderRepository {
+    Order save(Order order);
+    Order findById(Long id);
+}
+```
+
+**Adapter (REST):** The controller depends on the port (e.g. `PlaceOrderPort`) and delegates; the adapter is registered as a `@Bean` or the port is injected where the controller is defined. **Adapter (persistence):** A class in `internal/` implements `OrderRepository` using JdbcClient or JPA and is registered as a `@Bean`. **Adapter (messaging):** Outbound events can be published via `ApplicationEventPublisher` (in-process) or Kafka (see `references/spring-messaging.md`).
+
+Each Modulith module can apply hexagonal internally: public API = driving ports (use cases); `internal/` = driven adapters (repositories, external clients). See `references/spring-modulith.md` for module package structure.
+
+---
+
+## 2. Vertical Slice Architecture
+
+Organize by **feature / use case** instead of horizontal layers (controllers/, services/, repositories/). Each **vertical slice** contains everything needed for one capability: HTTP handler, application logic, persistence, and DTOs.
+
+**Package layout example (within an `orders` module):**
+
+```
+com.example.shop.orders/
+├── PlaceOrder/
+│   ├── PlaceOrderController.java   # REST endpoint
+│   ├── PlaceOrderCommand.java      # request DTO
+│   ├── PlaceOrderHandler.java      # use case
+│   └── OrderRepository.java        # port; impl in internal or same slice
+├── GetOrder/
+│   ├── GetOrderController.java
+│   ├── GetOrderHandler.java
+│   └── ...
+└── internal/
+    └── JdbcOrderRepository.java    # adapter shared by slices if needed
+```
+
+Each slice is a thin vertical: from HTTP (or message) down to persistence. Shared infrastructure (e.g. repository implementation) can live in `internal/` or a shared package. With **Modulith**, the module boundary is the root package (e.g. `orders/`); inside it you can structure by slices (PlaceOrder, GetOrder) or by role (OrderService, OrderController) — both are valid. Use Modulith’s verification and event-driven rules regardless; see `references/spring-modulith.md`.
+
+---
+
+## 3. DDD Mapping to Modulith
+
+| DDD concept | Modulith mapping |
+|-------------|------------------|
+| **Bounded context** | One root package = one module (e.g. `orders/`, `inventory/`). |
+| **Use case / application service** | Public service class in the module (e.g. `OrderService`) or a dedicated use-case class that the controller calls. |
+| **Aggregate** | Domain entity (or group of entities) that the module’s service loads and persists as a unit. See section 10 “DDD & Modulith” in `references/spring-modulith.md` for aggregate and domain repository. |
+| **Domain repository** | Interface in the module’s public or domain package; implementation in `internal/` (JdbcClient/JPA). Same as a “port” in hexagonal. |
+| **Domain events** | Often represented as application events published via `ApplicationEventPublisher` and consumed by other modules with `@ApplicationModuleListener`. See “DDD & Modulith” in `references/spring-modulith.md` for domain vs application events. |
+
+You do not need a separate “domain” package; the public API of the module can expose use cases and domain types (e.g. Order record). Keep infrastructure (repositories impl, HTTP clients) in `internal/` or in adapters.
+
+---
+
+## 4. CQRS (Optional)
+
+**CQRS** separates the **write model** (commands, aggregates, transactional consistency) from the **read model** (projections, queries, possibly different storage).
+
+**In a modular monolith (Modulith):** The module that owns the aggregate handles commands and publishes events (see transactional event listeners in `references/spring-modulith.md`). The same or another module can subscribe to those events and update a read model (e.g. a dedicated table or document store). Queries are served from the read model.
+
+**Across services:** Use Kafka (or another message broker) to publish domain events; consumer services build and maintain their own read models. See `references/spring-messaging.md` for producers and consumers. Ensure idempotency and ordering guarantees in consumers when building read models.
+
+Consider CQRS when read and write workloads or models diverge significantly (e.g. many reads with different shapes, or event-sourced writes with separate projections). For simple CRUD, a single model is often enough.
+
+---
+
+**Summary:** Use **ports (interfaces)** for use cases and repositories; implement them with **adapters** (REST, JPA/JdbcClient, Kafka). Structure by **Vertical Slice** per feature if it fits your team. Map **DDD** bounded contexts to **Modulith** modules and use the “DDD & Modulith” section in `references/spring-modulith.md` for aggregates and domain events. Use **CQRS** with event-driven updates when read and write models need to diverge; combine Modulith events and Kafka as needed.

package/skills/java-spring-framework/references/microservices-architecture.md

@@ -0,0 +1,77 @@
+# Microservices Architecture — Spring Boot 4
+
+**Spring Boot**: 4.0.x | Microservices design | **Jakarta EE**: 11
+
+This reference covers when to choose microservices vs a modular monolith, service boundaries, inter-service communication, API Gateway, and distributed observability. For building each service, use `references/spring-boot-4.md`, `references/spring-framework-7.md`, and for event-driven messaging `references/spring-messaging.md`. For a modular monolith alternative, see `references/spring-modulith.md`.
+
+---
+
+## Table of Contents
+
+1. [When to Choose Microservices vs Modular Monolith (Modulith)](#1-when-to-choose-microservices-vs-modular-monolith-modulith)
+2. [Service Boundaries](#2-service-boundaries)
+3. [Inter-Service Communication](#3-inter-service-communication)
+4. [API Gateway](#4-api-gateway)
+5. [Distributed Observability](#5-distributed-observability)
+6. [Config and Discovery (Optional)](#6-config-and-discovery-optional)
+
+---
+
+## 1. When to Choose Microservices vs Modular Monolith (Modulith)
+
+| Factor | Prefer Modulith (modular monolith) | Prefer Microservices |
+|--------|-------------------------------------|----------------------|
+| **Team structure** | Single team or few teams; shared codebase is manageable | Multiple teams owning different services; need independent delivery |
+| **Scaling** | Scale the whole application (e.g. more replicas of the same process) | Scale individual services (e.g. only the heavy-read service) |
+| **Deployment** | One deployable; simpler pipelines and rollbacks | Independent deploy per service; more operational complexity |
+| **Transactions** | Single database or local transactions across modules | Distributed transactions are hard; prefer eventual consistency and events |
+| **Latency** | In-process calls; low latency between modules | Network calls between services; higher latency and failure modes |
+| **Domain** | Domains are related; modules can communicate via events in one process | Bounded contexts are clearly separate (e.g. different companies or products) |
+
+Start with a **modular monolith** (Modulith) when the domain and team do not clearly demand separate deployments and scaling. Extract to microservices when you hit real limits (team boundaries, scaling, technology diversity). See `references/spring-modulith.md` for module structure and event-driven communication inside one application.
+
+---
+
+## 2. Service Boundaries
+
+- **One service = one bounded context** (or a cohesive subdomain). Avoid sharing a single database across services; each service typically owns its own data store. This reduces coupling and allows independent schema evolution.
+- **API contracts:** Define clear contracts between services. For REST, use **OpenAPI**; generate client DTOs or use a shared library. Document and version the API (e.g. URL path or header). See the OpenAPI/springdoc section in `references/spring-boot-4.md` for exposing and documenting REST APIs from each service.
+- **Database per service:** Each service uses its own database (or schema). Replicate data across services only via events or explicit sync APIs when necessary; avoid distributed transactions.
+
+---
+
+## 3. Inter-Service Communication
+
+**Synchronous (request/response):** Use **RestClient** (see `references/spring-framework-7.md`) to call other services. Share contracts (OpenAPI spec or DTOs). Handle timeouts, retries, and circuit breakers; Spring 7’s resilience annotations (`@Retryable`, `@CircuitBreaker`) can wrap outbound calls. For high-throughput or low-latency sync, consider gRPC in addition to REST.
+
+**Asynchronous (events):** Use **Kafka** (or similar) for cross-service events. The producer service publishes domain events; consumer services subscribe and update their own state. Prefer events when you need decoupling, resilience (consumer can process later), or audit. See `references/spring-messaging.md` for producers and `@KafkaListener` consumers. Design for **idempotency** (consumer can process the same message twice safely) and **ordering** (partition by key when order matters).
+
+**When to use which:** Use sync when the caller needs an immediate response (e.g. “get order by ID”). Use async when the operation can complete later or when multiple services react to the same event (e.g. “order placed” → inventory, notifications, analytics).
+
+---
+
+## 4. API Gateway
+
+An **API Gateway** sits in front of your services and handles routing, authentication/authorization at the edge, rate limiting, and sometimes aggregation. **Spring Cloud Gateway** is the Spring-based option: you configure routes (e.g. by path or host), filters (JWT validation, rate limiting), and point to backend services. Rate limiting at the gateway was mentioned in `references/spring-boot-4.md` (Rate limiting) as an alternative to in-app Bucket4j.
+
+Detailed route and filter configuration is outside this skill; see the [Spring Cloud Gateway documentation](https://docs.spring.io/spring-cloud-gateway/reference/) for setup. Each backend service remains a Spring Boot application with its own security (e.g. OAuth2 Resource Server) as in `references/spring-security-7.md`.
+
+---
+
+## 5. Distributed Observability
+
+**Distributed tracing:** Propagate a **trace ID** across service boundaries so a single request can be followed through multiple services. **OpenTelemetry** (OTEL) with W3C Trace Context headers is the standard. Each Spring Boot 4 service enables Actuator and OTEL as in `references/spring-boot-4.md` (Actuator & Observability). Ensure the HTTP client (RestClient) and Kafka producers/consumers propagate trace context; Boot’s OTEL integration typically does this when configured. The collector receives spans from all services and correlates them by trace ID.
+
+**Metrics and logs:** Each service exposes metrics (e.g. Prometheus) and logs in a consistent format. Aggregate metrics and logs in a central platform (e.g. Grafana, centralized logging). Use the same stack (Micrometer, OTEL) in every service for consistency. See `references/spring-boot-4.md` for Actuator, OTEL export, and health groups.
+
+---
+
+## 6. Config and Discovery (Optional)
+
+**Centralized config:** **Spring Cloud Config** can provide configuration (e.g. `application.yaml`) to multiple services from a central server. Use it when you need to change config without redeploying each service. See the [Spring Cloud Config documentation](https://docs.spring.io/spring-cloud-config/reference/) for setup.
+
+**Service discovery:** When services need to find each other by name (e.g. “order-service” instead of a fixed URL), use a discovery mechanism (e.g. Consul, Eureka, or Kubernetes services). Spring Cloud supports discovery clients; each service registers itself and resolves others by name. This is optional; you can also use static URLs or a gateway that routes by path.
+
+---
+
+**Summary:** Choose **microservices** when team boundaries, independent scaling, or deployment justify the operational cost; otherwise start with a **modular monolith** (Modulith). Define **service boundaries** around bounded contexts and avoid shared databases. Use **RestClient** for sync and **Kafka** for async communication; design for idempotency and ordering. Put an **API Gateway** (e.g. Spring Cloud Gateway) at the edge for routing and auth. Use **OpenTelemetry** and propagate trace context so you get **distributed observability** across all services.

package/skills/java-spring-framework/references/spring-modulith.md

@@ -14,6 +14,7 @@
 7. [Module Integration Testing](#7-module-integration-testing)
 8. [Generating Documentation](#8-generating-documentation)
 9. [Common Pitfalls](#9-common-pitfalls)
+10. [DDD & Modulith](#10-ddd--modulith)
 
 ---
 
@@ -231,3 +232,13 @@ Output lands in `target/spring-modulith-docs/` (Maven) or `build/spring-modulith
 | **Forgetting the verification test in CI** | Add the module verification test (section 3) to your CI pipeline so boundary violations are caught on every commit. |
 | **Direct service calls across modules** | One module must not inject another module's service and call it directly. Use `ApplicationEventPublisher` and `@ApplicationModuleListener` (or transactional events) for cross-module communication. |
 | **Putting shared DTOs in one module's internal** | Types used in events or APIs consumed by several modules belong in a `shared/` (or similar) package, not in one module's `internal/`. |
+
+---
+
+## 10. DDD & Modulith
+
+**Aggregate:** An aggregate is a cluster of entities and value objects with a **root entity** that enforces invariants. It is loaded and persisted as a unit. In Modulith, a module usually has one or more aggregates; the module’s public service (e.g. `OrderService`) orchestrates the aggregate: it loads the root via a repository, mutates it, and saves. Example: `Order` as aggregate root; `OrderService.placeOrder(...)` loads or creates an `Order`, applies domain logic, calls `OrderRepository.save(order)`, and publishes events. The repository interface lives in the module API; the implementation (JdbcClient or JPA) lives in `internal/`.
+
+**Domain repository:** A **domain repository** is an interface that exposes only domain operations (e.g. `save(Order)`, `findById(OrderId)`), without infrastructure details. In Spring terms, that interface is the **port**; the implementation in `internal/` (using JdbcClient, JPA, etc.) is the **adapter**. The repository you already use for the module (e.g. `OrderRepository`) acts as the domain repository if it only exposes domain-centric methods and returns domain types or optionals.
+
+**Domain events vs application events:** A **domain event** is something that happened in the domain (e.g. “OrderPlaced”). An **application event** is the mechanism: you publish with `ApplicationEventPublisher` and other modules listen with `@ApplicationModuleListener`. In practice with Modulith, the events you publish between modules are application events that typically **represent** domain events of the publishing module. The payload (e.g. `OrderPlacedEvent`) carries the domain data. Section 5 (Event-Driven Inter-Module Communication) and section 6 (Transactional Event Listeners) describe how to publish and consume these; here we only distinguish: domain event = meaning; application event = Spring’s delivery mechanism.