spring-boot4-skill 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.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
+
+- **Skill:** New references: `spring-redis.md` (Redis, RedisTemplate, cache backend, session store, pub/sub), `spring-data-mongodb.md` (MongoDB, MongoTemplate, MongoRepository, documents, transactions, indexes), `spring-graphql.md` (Spring for GraphQL, schema, @QueryMapping/@MutationMapping, Records).
+- **Skill:** spring-boot-4.md: new section 14 (API documentation — OpenAPI/springdoc) and section 15 (Scheduling — @Scheduled, cron, virtual threads).
+- **Skill:** spring-framework-7.md: new section 14 (Bean Validation 3.1 — @Valid, @NotNull, @Size, @Email, Records).
+- **Skill:** SKILL.md Reference Files table: Redis, MongoDB, GraphQL rows; extended Load when for spring-boot-4 (OpenAPI/springdoc, scheduling) and spring-framework-7 (Bean Validation, @Valid); Quick decision mermaid nodes for Redis, MongoDB, GraphQL.
+- **README:** Skill reference table: spring-redis.md, spring-data-mongodb.md, spring-graphql.md; extended descriptions for spring-boot-4 and spring-framework-7.
+
+[1.4.0]: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework/compare/v1.3.0...v1.4.0
+
 ## [1.3.0] - 2026-02-21
 
 ### Added

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/spring-boot4-skill.svg)](https://www.npmjs.com/package/spring-boot4-skill)
 
 > **2026-standard** project scaffolder + Claude Code AI skill for Java / Spring development.
-> By [AyrtonAldayr](https://github.com/AyrtonAldayr) · **v1.3.0**
+> By [AyrtonAldayr](https://github.com/AyrtonAldayr) · **v1.4.0**
 
 This repository provides two tools in one:
 
@@ -133,11 +133,16 @@ Once installed, Claude Code acts as a **Senior Spring Boot 4 architect**:
 
 | File | Contents |
 |---|---|
-| `skills/java-spring-framework/references/spring-framework-7.md` | All Spring 7 APIs with code examples |
-| `skills/java-spring-framework/references/spring-boot-4.md` | Boot 4: native, virtual threads, testing (Testcontainers), reactive stack, rate limiting, connection pools, caching, performance |
+| `skills/java-spring-framework/references/spring-framework-7.md` | All Spring 7 APIs, Bean Validation, @Valid |
+| `skills/java-spring-framework/references/spring-boot-4.md` | Boot 4: native, virtual threads, testing, reactive stack, rate limiting, connection pools, caching, performance, OpenAPI, scheduling |
 | `skills/java-spring-framework/references/spring-security-7.md` | OAuth2 Resource Server, JWT, method security, CORS |
+| `skills/java-spring-framework/references/spring-redis.md` | Redis, cache distribuido, session store |
+| `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-modulith.md` | Module structure, events, integration testing, common pitfalls |
+| `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, 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 |
 
@@ -159,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.3.0",
+  "version": "1.5.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?}
@@ -44,6 +48,12 @@ flowchart TD
     M -->|Yes| N[spring-messaging.md]
     A --> O{Rate limit / resources / performance?}
     O -->|Yes| P[spring-boot-4.md]
+    A --> Q{Redis / cache distribuido?}
+    Q -->|Yes| R[spring-redis.md]
+    A --> S{MongoDB / document DB?}
+    S -->|Yes| T[spring-data-mongodb.md]
+    A --> U{GraphQL API?}
+    U -->|Yes| V[spring-graphql.md]
 ```
 
 ## Mandatory Workflow
@@ -80,10 +90,15 @@ Load these as needed — do not load all at once:
 
 | Topic | File | Load when |
 |---|---|---|
-| Spring Framework 7 APIs | `references/spring-framework-7.md` | Framework-level features: versioning, resilience, JSpecify, SpEL, streaming |
-| Spring Boot 4 features | `references/spring-boot-4.md` | Boot auto-config, Actuator, native images, testing, virtual threads, rate limiting, connection pools, resource metrics, caching, performance tuning |
+| Spring Framework 7 APIs | `references/spring-framework-7.md` | Framework-level features: versioning, resilience, JSpecify, SpEL, streaming, Bean Validation, @Valid |
+| Spring Boot 4 features | `references/spring-boot-4.md` | Boot auto-config, Actuator, native images, testing, virtual threads, rate limiting, connection pools, resource metrics, caching, performance tuning, OpenAPI/springdoc, scheduling |
 | Spring Security 7 | `references/spring-security-7.md` | OAuth2 Resource Server, JWT, method security, CORS, authentication/authorization |
+| Redis | `references/spring-redis.md` | Redis, cache distribuido, session store |
+| 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 |
-| Spring Modulith | `references/spring-modulith.md` | Domain-driven module design, event-driven architecture |
+| GraphQL | `references/spring-graphql.md` | GraphQL API, Spring for GraphQL |
+| 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-boot-4.md

@@ -18,6 +18,8 @@
 11. [Reactive Stack (R2DBC + WebFlux)](#11-reactive-stack-r2dbc--webflux)
 12. [Rate Limiting](#12-rate-limiting)
 13. [Resources & Performance](#13-resources--performance)
+14. [API Documentation (OpenAPI / springdoc)](#14-api-documentation-openapi--springdoc)
+15. [Scheduling](#15-scheduling)
 
 ---
 
@@ -598,3 +600,87 @@ Use short TTLs or size limits to avoid stale or unbounded caches.
 - **Pool sizing:** Set HikariCP (or R2DBC pool) size based on observed metrics (connections in use, pending); avoid over-provisioning.
 - **N+1:** Avoid N+1 queries in JPA (e.g. `@EntityGraph`, fetch joins, or DTO projections) so a single request does not open many statements.
 - **Observability:** Use Actuator/Prometheus and traces (section 4) to find bottlenecks (slow endpoints, DB, or external calls) and tune accordingly. No JVM-level tuning (heap, GC) is covered here.
+
+---
+
+## 14. API Documentation (OpenAPI / springdoc)
+
+Use **springdoc-openapi** to expose OpenAPI 3 spec and Swagger UI from your REST controllers. The JSON/YAML spec is consumed by clients and code generators; the UI is useful in development.
+
+**Dependency:**
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0")  // align with Boot 4
+}
+```
+
+**application.yaml:**
+
+```yaml
+springdoc:
+  api-docs:
+    path: /v3/api-docs
+  swagger-ui:
+    path: /swagger-ui.html
+```
+
+Document controllers with `@Operation` and `@Parameter`:
+
+```java
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+@RestController
+@RequestMapping("/api/products")
+@Tag(name = "Products", description = "Product API")
+public class ProductController {
+
+    @GetMapping("/{id}")
+    @Operation(summary = "Get product by ID")
+    public Product get(@Parameter(description = "Product ID") @PathVariable String id) {
+        return productService.findById(id);
+    }
+}
+```
+
+The OpenAPI spec is available at `springdoc.api-docs.path` (default `/v3/api-docs`); Swagger UI at `springdoc.swagger-ui.path`. Protect these endpoints in production via Spring Security 7 (e.g. allow only for authenticated users or internal network). See [springdoc documentation](https://springdoc.org/) for grouping, security schemes, and more.
+
+---
+
+## 15. Scheduling
+
+Use `@EnableScheduling` and `@Scheduled` for periodic tasks (cron, fixed rate, or fixed delay).
+
+**Enable scheduling:**
+
+```java
+@SpringBootApplication
+@EnableScheduling
+public class Application { ... }
+```
+
+**Scheduled component:**
+
+```java
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+@Component
+public class SyncJob {
+
+    @Scheduled(fixedRate = 60000)  // every 60 seconds
+    public void sync() {
+        // run task
+    }
+
+    @Scheduled(cron = "0 0 * * * *")  // every hour at minute 0
+    public void hourlyReport() {
+        // run task
+    }
+}
+```
+
+With **virtual threads** enabled (section 6), scheduled tasks run on virtual threads when the default task scheduler is used; blocking work in the task does not block platform threads. For a custom `TaskScheduler` (e.g. thread pool size), define a `TaskScheduler` bean and configure as needed. Spring Batch is not covered here; for batch jobs (chunk-based reading/writing), see Spring Batch documentation.

package/skills/java-spring-framework/references/spring-data-mongodb.md

@@ -0,0 +1,168 @@
+# Spring Data MongoDB — Boot 4
+
+**Spring Boot**: 4.0.x | **Spring Data MongoDB**: aligned with Boot BOM | **Jakarta EE**: 11
+
+---
+
+## Table of Contents
+
+1. [Dependencies](#1-dependencies)
+2. [application.yaml](#2-applicationyaml)
+3. [Documents and @Document](#3-documents-and-document)
+4. [MongoRepository](#4-mongorepository)
+5. [MongoTemplate](#5-mongotemplate)
+6. [Transactions and indexes](#6-transactions-and-indexes)
+
+---
+
+## 1. Dependencies
+
+Spring Boot 4 BOM manages Spring Data MongoDB. Add the starter:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-data-mongodb")
+}
+```
+
+---
+
+## 2. application.yaml
+
+```yaml
+spring:
+  data:
+    mongodb:
+      uri: mongodb://localhost:27017/mydb
+      # or separately:
+      # host: localhost
+      # port: 27017
+      # database: mydb
+      # username: app
+      # password: secret
+```
+
+For connection pool tuning (MongoDB driver):
+
+```yaml
+spring:
+  data:
+    mongodb:
+      uri: mongodb://localhost:27017/mydb
+      auto-index-creation: true
+```
+
+---
+
+## 3. Documents and @Document
+
+Use a Java record or class with `@Document` and `@Id`. Prefer records for DTOs; for entities that need lazy loading or complex mapping, a class is fine.
+
+```java
+import org.springframework.data.annotation.Id;
+import org.springframework.data.mongodb.core.mapping.Document;
+import org.springframework.data.mongodb.core.index.Indexed;
+
+@Document(collection = "products")
+public record Product(
+    @Id String id,
+    String name,
+    @Indexed String sku,
+    java.math.BigDecimal price
+) {}
+```
+
+For mutable entities (e.g. append-only fields), use a class with getters/setters and `@Id` on the identifier field.
+
+---
+
+## 4. MongoRepository
+
+Extend `MongoRepository<Entity, IdType>` for CRUD and query methods. Use `String` as ID type for MongoDB ObjectId-backed ids.
+
+```java
+import org.springframework.data.mongodb.repository.MongoRepository;
+import java.util.List;
+
+public interface ProductRepository extends MongoRepository<Product, String> {
+
+    List<Product> findByName(String name);
+
+    List<Product> findByPriceBetween(java.math.BigDecimal min, java.math.BigDecimal max);
+
+    boolean existsBySku(String sku);
+}
+```
+
+Custom queries with `@Query`:
+
+```java
+@Query("{ 'name' : { $regex: ?0, $options: 'i' } }")
+List<Product> findByNameRegex(String pattern);
+```
+
+Use `MongoRepository` when you need standard CRUD and derived queries; use `MongoTemplate` for dynamic queries or aggregations (see [Spring Data MongoDB docs](https://docs.spring.io/spring-data/mongodb/reference/) for aggregation pipelines).
+
+---
+
+## 5. MongoTemplate
+
+For programmatic or dynamic queries, inject `MongoTemplate`:
+
+```java
+import org.springframework.data.mongodb.core.MongoTemplate;
+import org.springframework.data.mongodb.core.query.Criteria;
+import org.springframework.data.mongodb.core.query.Query;
+import org.springframework.data.mongodb.core.query.Update;
+import org.springframework.stereotype.Service;
+
+@Service
+public class ProductService {
+
+    private final MongoTemplate mongo;
+
+    public ProductService(MongoTemplate mongo) {
+        this.mongo = mongo;
+    }
+
+    public Product findById(String id) {
+        return mongo.findById(id, Product.class);
+    }
+
+    public List<Product> findBySku(String sku) {
+        return mongo.find(Query.query(Criteria.where("sku").is(sku)), Product.class);
+    }
+
+    public Product insert(Product product) {
+        return mongo.insert(product);
+    }
+
+    public void updatePrice(String id, java.math.BigDecimal price) {
+        mongo.updateFirst(
+            Query.query(Criteria.where("id").is(id)),
+            Update.update("price", price),
+            Product.class
+        );
+    }
+}
+```
+
+---
+
+## 6. Transactions and indexes
+
+**Transactions:** Supported when MongoDB is run as a replica set. Enable with `@Transactional` on the method (or class). Spring Data MongoDB uses the same transaction manager as other Spring Data stores when configured.
+
+```java
+@Transactional
+public void transfer(Product from, Product to, int qty) {
+    // multiple read/write operations in one transaction
+}
+```
+
+**Indexes:** Use `@Indexed` on fields for single-field indexes. For compound or custom indexes, create them at startup via `MongoTemplate.indexOps(Product.class).ensureIndex(new Index().on("name", Sort.Direction.ASC).on("price", Sort.Direction.DESC))` or with `@CompoundIndex` on the document class. Set `spring.data.mongodb.auto-index-creation: true` in development; in production, manage indexes via migrations or infrastructure as code.
+
+---
+
+**Summary:** Use `spring-boot-starter-data-mongodb` with Boot 4 BOM, configure URI (or host/port/database) in `application.yaml`, and model documents with `@Document` and `@Id`. Use `MongoRepository` for CRUD and derived queries; use `MongoTemplate` for dynamic or programmatic access. Use transactions on replica sets and define indexes via `@Indexed` or programmatic API. For aggregation pipelines, see the official Spring Data MongoDB reference.

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

@@ -20,6 +20,7 @@ For **reactive applications (WebFlux + R2DBC)**, combine this reference with the
 11. [Enhanced PathPattern](#11-enhanced-pathpattern)
 12. [RestTestClient (Testing)](#12-resttestclient-testing)
 13. [Removed APIs Migration](#13-removed-apis-migration)
+14. [Bean Validation 3.1](#14-bean-validation-31)
 
 ---
 
@@ -316,3 +317,39 @@ class ProductControllerTest {
 | XML Spring MVC config | `WebMvcConfigurer` (Java) |
 | `suffixPatternMatch` | Explicit media types |
 | `trailingSlashMatch` | Explicit URI templates |
+
+---
+
+## 14. Bean Validation 3.1
+
+Spring MVC and WebFlux support **Jakarta Bean Validation 3.1** (Boot 4 brings the dependency). Use `@Valid` (or `@Validated`) on `@RequestBody`, and optionally on `@RequestParam` / path variables with group validation or custom validators.
+
+**DTO with constraints:**
+
+```java
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+
+public record CreateUserRequest(
+    @NotBlank(message = "Name is required")
+    @Size(min = 1, max = 100)
+    String name,
+
+    @NotBlank
+    @Email(message = "Must be a valid email")
+    String email
+) {}
+```
+
+**Controller:**
+
+```java
+@PostMapping("/api/users")
+public ResponseEntity<User> create(@Valid @RequestBody CreateUserRequest request) {
+    User user = userService.create(request);
+    return ResponseEntity.status(HttpStatus.CREATED).body(user);
+}
+```
+
+Validation failures trigger `MethodArgumentNotValidException`; handle them in an `@ExceptionHandler` to return 400 with error details. Standard annotations include `@NotNull`, `@NotBlank`, `@Size`, `@Min`, `@Max`, `@Email`, `@Pattern`. For validation groups or custom validators, use `@Validated` with a group class or implement `ConstraintValidator`; see the Bean Validation spec for details.

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

@@ -0,0 +1,150 @@
+# Spring for GraphQL — Boot 4
+
+**Spring Boot**: 4.0.x | **Spring for GraphQL**: aligned with Boot BOM | **Jakarta EE**: 11
+
+---
+
+## Table of Contents
+
+1. [Dependencies](#1-dependencies)
+2. [application.yaml](#2-applicationyaml)
+3. [Schema (SDL)](#3-schema-sdl)
+4. [Query and mutation controllers](#4-query-and-mutation-controllers)
+5. [Records for types](#5-records-for-types)
+6. [Security](#6-security)
+
+---
+
+## 1. Dependencies
+
+Spring Boot 4 BOM manages Spring for GraphQL. Add the starter:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-graphql")
+    implementation("org.springframework.boot:spring-boot-starter-web")  // or webflux
+}
+```
+
+---
+
+## 2. application.yaml
+
+```yaml
+spring:
+  graphql:
+    graphiql:
+      enabled: true   # dev: UI at /graphiql
+    path: /graphql    # default
+    cors:
+      allowed-origins: "https://myapp.example.com"
+```
+
+The GraphQL endpoint is exposed at `spring.graphql.path` (default `/graphql`). Use the same `SecurityFilterChain` as for REST to protect it; see section 6.
+
+---
+
+## 3. Schema (SDL)
+
+Place schema files under `src/main/resources/graphql/**/*.graphqls` (or `.graphqls`). Boot auto-picks them.
+
+Example `src/main/resources/graphql/schema.graphqls`:
+
+```graphql
+type Query {
+  product(id: ID!): Product
+  products(first: Int = 10): [Product!]!
+}
+
+type Mutation {
+  createProduct(input: CreateProductInput!): Product!
+}
+
+type Product {
+  id: ID!
+  name: String!
+  sku: String!
+  price: Float!
+}
+
+input CreateProductInput {
+  name: String!
+  sku: String!
+  price: Float!
+}
+```
+
+---
+
+## 4. Query and mutation controllers
+
+Use `@Controller` and `@QueryMapping` / `@MutationMapping`. Method names match schema field names by default, or specify with the annotation.
+
+```java
+import org.springframework.graphql.data.method.annotation.Argument;
+import org.springframework.graphql.data.method.annotation.MutationMapping;
+import org.springframework.graphql.data.method.annotation.QueryMapping;
+import org.springframework.stereotype.Controller;
+
+@Controller
+public class ProductGraphQLController {
+
+    private final ProductService productService;
+
+    public ProductGraphQLController(ProductService productService) {
+        this.productService = productService;
+    }
+
+    @QueryMapping
+    public Product product(@Argument String id) {
+        return productService.findById(id);
+    }
+
+    @QueryMapping
+    public java.util.List<Product> products(@Argument Integer first) {
+        int limit = first != null ? first : 10;
+        return productService.findAll(limit);
+    }
+
+    @MutationMapping
+    public Product createProduct(@Argument CreateProductInput input) {
+        return productService.create(input.name(), input.sku(), input.price());
+    }
+}
+```
+
+For nested types (e.g. `Product` has a `category` field), use `@SchemaMapping` on a method that takes the parent object and returns the nested one:
+
+```java
+@SchemaMapping(typeName = "Product", field = "category")
+public Category category(Product product) {
+    return categoryService.findById(product.categoryId());
+}
+```
+
+---
+
+## 5. Records for types
+
+Use Java records for DTOs and inputs. Spring for GraphQL maps them to the schema:
+
+```java
+public record CreateProductInput(String name, String sku, double price) {}
+
+public record Product(String id, String name, String sku, double price, String categoryId) {}
+```
+
+Ensure record component names align with schema field names (or use `@JsonProperty` if names differ). Use `jakarta.*` and JSpecify where applicable for nullability in the API layer.
+
+---
+
+## 6. Security
+
+GraphQL is exposed over HTTP like REST. Protect the GraphQL path in your `SecurityFilterChain` (see `references/spring-security-7.md`): require authentication for `/graphql` and optionally allow anonymous for introspection in dev only. For authenticated GraphQL, clients typically send the same token (e.g. Bearer JWT) in the `Authorization` header; the resolver can access the current user via `SecurityContextHolder` or a custom context in the GraphQL execution.
+
+Restrict introspection in production if you do not want to expose the full schema to unauthenticated clients.
+
+---
+
+**Summary:** Use `spring-boot-starter-graphql` with Boot 4 BOM, define the schema in `.graphqls` under `resources/graphql`, and implement queries and mutations with `@Controller`, `@QueryMapping`, and `@MutationMapping`. Use records for input and output types. Secure the GraphQL endpoint with the same Spring Security 7 configuration as REST.

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.

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

@@ -0,0 +1,183 @@
+# Spring Data Redis — Boot 4
+
+**Spring Boot**: 4.0.x | **Spring Data Redis**: aligned with Boot BOM | **Jakarta EE**: 11
+
+---
+
+## Table of Contents
+
+1. [Dependencies](#1-dependencies)
+2. [application.yaml](#2-applicationyaml)
+3. [RedisTemplate and StringRedisTemplate](#3-redistemplate-and-stringredistemplate)
+4. [Redis as cache backend](#4-redis-as-cache-backend)
+5. [Pub/Sub (optional)](#5-pubsub-optional)
+6. [Session store (optional)](#6-session-store-optional)
+
+---
+
+## 1. Dependencies
+
+Spring Boot 4 BOM manages Spring Data Redis. Add the starter:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-data-redis")
+    // Optional: use Redis as distributed cache backend (see section 4)
+    // implementation("org.springframework.boot:spring-boot-starter-cache")
+}
+```
+
+For connection pooling (Lettuce is the default client):
+
+```kotlin
+// Lettuce is included transitively; no extra dependency for basic use
+```
+
+---
+
+## 2. application.yaml
+
+```yaml
+spring:
+  data:
+    redis:
+      host: localhost
+      port: 6379
+      password:                    # set in production
+      timeout: 2000ms
+      lettuce:
+        pool:
+          max-active: 16
+          max-idle: 8
+          min-idle: 4
+```
+
+For a single Redis URL:
+
+```yaml
+spring:
+  data:
+    redis:
+      url: redis://user:password@localhost:6379/0
+```
+
+---
+
+## 3. RedisTemplate and StringRedisTemplate
+
+Use `StringRedisTemplate` for string keys/values; use `RedisTemplate<String, Object>` (with a configured serializer) for objects. Prefer strings when possible for simplicity and interoperability.
+
+```java
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.stereotype.Service;
+
+@Service
+public class TokenStore {
+
+    private final StringRedisTemplate redis;
+
+    public TokenStore(StringRedisTemplate redis) {
+        this.redis = redis;
+    }
+
+    public void save(String key, String value, java.time.Duration ttl) {
+        var ops = redis.opsForValue();
+        ops.set(key, value, ttl);
+    }
+
+    public String get(String key) {
+        return redis.opsForValue().get(key);
+    }
+}
+```
+
+Hashes and lists:
+
+```java
+redis.opsForHash().put("user:1", "name", "Alice");
+redis.opsForHash().put("user:1", "email", "alice@example.com");
+redis.opsForList().rightPush("queue:tasks", taskId);
+```
+
+Use Records or simple DTOs when storing JSON; serialize with Jackson and store as string, or use `RedisTemplate<String, YourRecord>` with `GenericJackson2JsonRedisSerializer` (ensure Jakarta and Boot 4 Jackson versions align).
+
+---
+
+## 4. Redis as cache backend
+
+For distributed caching, use Redis instead of Caffeine. Enable caching and set the cache type to Redis:
+
+```yaml
+spring:
+  cache:
+    type: redis
+    cache-names: products,users
+  data:
+    redis:
+      host: localhost
+      port: 6379
+```
+
+```java
+@SpringBootApplication
+@EnableCaching
+public class Application { ... }
+```
+
+Use `@Cacheable`, `@CacheEvict`, `@CachePut` as with any Spring Cache backend. TTL can be configured per cache via `spring.cache.redis.time-to-live` or custom `RedisCacheConfiguration` if needed.
+
+Dependencies: `spring-boot-starter-cache` and `spring-boot-starter-data-redis`. No extra starter for Redis cache; Boot auto-configures it when `type: redis` is set.
+
+---
+
+## 5. Pub/Sub (optional)
+
+Publish messages with `RedisTemplate`:
+
+```java
+redis.convertAndSend("notifications", "User signed up: " + userId);
+```
+
+Subscribe with a listener:
+
+```java
+import org.springframework.data.redis.connection.Message;
+import org.springframework.data.redis.connection.MessageListener;
+import org.springframework.data.redis.listener.ChannelTopic;
+import org.springframework.data.redis.listener.RedisMessageListenerContainer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class RedisPubSubConfig {
+
+    @Bean
+    RedisMessageListenerContainer redisMessageListenerContainer(
+            org.springframework.data.redis.connection.RedisConnectionFactory factory,
+            NotificationSubscriber subscriber) {
+        var container = new RedisMessageListenerContainer();
+        container.setConnectionFactory(factory);
+        container.addMessageListener(subscriber, new ChannelTopic("notifications"));
+        return container;
+    }
+}
+```
+
+Implement `MessageListener` and handle `message.getBody()` in `onMessage`.
+
+---
+
+## 6. Session store (optional)
+
+To store HTTP sessions in Redis, add Spring Session:
+
+```kotlin
+implementation("org.springframework.session:spring-session-data-redis")
+```
+
+Configure session timeout and optionally namespace in `application.yaml`. Sessions are then stored in Redis instead of in-memory; suitable for multi-instance deployments. Security and session configuration remain in Spring Security 7; see `references/spring-security-7.md` for auth.
+
+---
+
+**Summary:** Use `spring-boot-starter-data-redis` with Boot 4 BOM, configure host/port/pool in `application.yaml`, and use `StringRedisTemplate` or `RedisTemplate` for keys/values, hashes, and lists. Use `spring.cache.type=redis` for distributed cache; optionally use pub/sub or Spring Session Data Redis for sessions.