docs: add claude initial files

AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md
+
+This file provides guidance to AI agents when working in this repository.
+
+## Repository Overview
+
+Maven monorepo of 23 Java library modules for cloud-native microservices on Kubernetes.
+Java 21, groupId `com.netcracker.cloud`, distributed via GitHub Maven Packages.
+
+## Module Map
+
+| Module | Purpose |
+|--------|---------|
+| `core-microservice-dependencies` | Central BOM (`cloud-core-java-bom`) for dependency versions |
+| `core-springboot-starter` | Spring Boot parent POM aggregating microservice essentials |
+| `core-utils` | TLS config and Kubernetes projected-volume token utilities |
+| `core-error-handling` | Error-code-based exception hierarchy with REST layer support |
+| `core-context-propagation` | Propagates execution context across HTTP/messaging boundaries |
+| `core-context-propagation-quarkus` | Quarkus variant of context propagation |
+| `core-microservice-framework` | Spring microservice scaffolding (routing, security, M2M RestClient) |
+| `core-microservice-framework-extensions` | SpringDoc, health indicators, metrics extensions |
+| `core-rest-libraries` | WebClient utilities, route registration, config-server loader, security |
+| `core-restclient` | Abstraction API over WebClient (preferred) / RestTemplate (deprecated) |
+| `core-mongo-evolution` | MongoDB schema migration tool (analogous to Flyway) |
+| `core-process-orchestrator` | Persistent task scheduling with dependency management |
+| `core-blue-green-state-monitor` | Consul-based blue/green deployment state monitoring |
+| `core-blue-green-state-monitor-quarkus` | Quarkus variant of blue/green monitoring |
+| `core-junit-k8s-extension` | JUnit 5 extension for Kubernetes integration tests |
+| `core-quarkus-extensions` | Quarkus extensions: context, security, logging, DBaaS, MaaS, routes |
+| `dbaas-client` | Database-as-a-Service client (PostgreSQL, MongoDB, Cassandra, OpenSearch, ClickHouse, ArangoDB, Redis) |
+| `maas-client` | Messaging-as-a-Service core client (Kafka + RabbitMQ, framework-agnostic) |
+| `maas-client-spring` | Spring Boot MaaS integration (Kafka + RabbitMQ) |
+| `maas-client-quarkus` | Quarkus MaaS integration |
+| `maas-declarative-client-commons` | Declarative Kafka client common utilities |
+| `maas-declarative-client-spring` | Spring declarative Kafka client |
+| `maas-declarative-client-quarkus` | Quarkus declarative Kafka client |
+
+## Build & Test
+
+```bash
+# Use -B -ntp -q to suppress progress/download noise; drop -q to diagnose failures
+mvn verify -B -ntp -q -T 1C                        # full parallel build + tests
+mvn verify -B -ntp -q -pl <module> -am             # module + its transitive deps from root
+mvn verify -B -ntp -q                              # from a module directory
+mvn test -B -ntp -q -Dtest=ClassName               # single test class
+mvn test -B -ntp -q -Dtest=ClassName#methodName    # single test method
+mvn verify -B -ntp -q -DskipTests                  # compile only, skip tests
+mvn deploy -B -ntp -q -T 1C                        # build and publish to GitHub Packages
+```
+
+## Code Conventions
+
+- Java 21, UTF-8, 2-space indent (enforced by `.editorconfig` present in each module)
+- Lombok: `@Data`, `@Builder`, `@Slf4j` — avoid `@SneakyThrows`
+- No Spring/Quarkus imports in pure-Java core modules (`core-utils`, `core-process-orchestrator`, `maas-client/client`)
+- RestTemplate sub-modules are deprecated — new features go to WebClient equivalents only
+
+## Dependency Management
+
+- `cloud-core-java-bom` (`core-microservice-dependencies/cloud-core-java-bom/pom.xml`) is an external public BOM — it imports internal sub-BOMs (dbaas-client, rest-libraries, maas-client, etc.) and pins their versions. Do not add arbitrary third-party deps here; version-pin those inside the relevant sub-BOM.
+- New Quarkus extensions must also be registered in `core-quarkus-extensions/cloud-core-quarkus-bom/cloud-core-quarkus-bom-publish/pom.xml`
+- New modules inherit from the nearest `*-parent` POM and import `cloud-core-java-bom` via `<dependencyManagement>`
+
+## CI / Commit Rules
+
+- Commit messages must follow Conventional Commits (enforced by `.github/workflows/pr-conventional-commits.yaml`)
+- PRs trigger: `mvn verify -T 1C` + SonarCloud (`.github/workflows/maven-verify.yml`)
+- Merges to main trigger: `mvn deploy -T 1C` with GPG signing (`.github/workflows/maven-deploy.yml`)
+
+## Architecture Patterns
+
+- **Spring vs Quarkus**: parallel implementations share a pure-Java core (e.g. `blue-green-state-monitor-java` + Spring module + Quarkus module)
+- **BOM hierarchy**: new Spring modules import `cloud-core-java-bom` via `<dependencyManagement>`; new Quarkus modules use `cloud-core-quarkus-bom-publish`. Neither BOM accepts arbitrary third-party deps directly — version-pin those inside the appropriate sub-BOM.
+- **Jandex index**: `core-context-propagation` uses Jandex for provider discovery — run `mvn generate-sources` after adding a new context provider
+- **Lombok**: delombok sources generated by `lombok-maven-plugin` during build
+
+## Docker / Testcontainers
+
+Required for integration tests in: `core-blue-green-state-monitor`, `dbaas-client`, `maas-declarative-client-commons`.
+Use `mvn verify -DskipTests` to skip those tests when Docker is unavailable.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-blue-green-state-monitor-quarkus/AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md — core-blue-green-state-monitor-quarkus
+
+## Module
+
+Quarkus CDI integration of `blue-green-state-monitor-java`. Replaces the Spring auto-configuration with Quarkus Arc producers and Quarkus lifecycle event listeners.
+
+## Build
+
+```bash
+mvn verify
+```
+
+## Extension Guide
+
+- Consul watch and lock logic lives in `core-blue-green-state-monitor/blue-green-state-monitor-java` — do not duplicate it here.
+- New CDI producer → add to `src/main/java/` following existing Arc `@Produces` pattern.
+
+## Notes
+
+- CDI (Arc) producers only — no Spring annotations.

core-blue-green-state-monitor-quarkus/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-blue-green-state-monitor/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md — core-blue-green-state-monitor
+
+## Module
+
+Watches Consul KV for blue/green deployment state changes and provides lock management so services can pause work during a deployment flip.
+
+## Sub-modules
+
+- **`blue-green-state-monitor-java`** — pure Java core: Consul watch loop, state parser, lock API.
+- **`blue-green-state-monitor-spring`** — Spring Boot auto-configuration: exposes `BlueGreenStatePublisher`, `GlobalMutexService`, `MicroserviceMutexService` beans and integrates with Spring lifecycle events.
+- **`blue-green-state-monitor-report-aggregate`** — JaCoCo aggregate.
+
+## Build
+
+```bash
+mvn verify -B -ntp -q                  # requires Docker (Testcontainers + real Consul)
+mvn verify -B -ntp -q -DskipTests      # skip integration tests when Docker is unavailable
+```
+
+## Key Concepts
+
+- **Global lock** (`GlobalMutexService`) — blocks all services until the operator clears it.
+- **Microservice lock** (`MicroserviceMutexService`) — targets a specific service; others continue.
+- Integration tests spin up a real Consul instance via Testcontainers 2.0.4.
+
+## Extension Guide
+
+- New lock type → extend lock API in `blue-green-state-monitor-java`; add Spring bean in `blue-green-state-monitor-spring`.
+- Keep framework-specific code out of `blue-green-state-monitor-java`.

core-blue-green-state-monitor/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-context-propagation-quarkus/AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md — core-context-propagation-quarkus
+
+## Module
+
+Quarkus CDI-native port of `core-context-propagation`. Provides the same context extraction/injection pipeline integrated with Quarkus Arc and Vert.x request pipeline instead of Spring MVC.
+
+## Sub-modules
+
+- **`context`** — Arc CDI producers and Vert.x interceptors for inbound/outbound context propagation.
+- **`framework-contexts`** — Quarkus-specific wiring for built-in contexts (shared definitions from `core-context-propagation/framework-contexts`).
+- **`integration-tests`** — integration test suite.
+- **`bom`** — BOM for consumers.
+- **`build-parent`** — shared build POM.
+- **`report-aggregate`** — JaCoCo aggregate.
+
+## Build
+
+```bash
+mvn verify
+mvn generate-sources        # rebuild Jandex index after adding a new provider
+```
+
+## Extension Guide
+
+- New context → add the `ContextProvider` implementation in `core-context-propagation/framework-contexts` first; add a Quarkus-specific shim here only if the integration requires it.
+- Jandex index rebuilt by `io.smallrye:jandex-maven-plugin` during `generate-sources`.
+
+## Notes
+
+- CDI (Arc) producers only — no Spring annotations.

core-context-propagation-quarkus/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-context-propagation/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md — core-context-propagation
+
+## Module
+
+Propagates named execution contexts (headers, trace IDs, locale, etc.) transparently across HTTP and messaging boundaries in Spring microservices.
+
+## Sub-modules
+
+- **`context-propagation-core`** — provider SPI, context registry, `ContextSnapshot`, storage strategies.
+- **`framework-contexts`** — built-in contexts: `Accept-Language`, `X-Request-Id` (auto-generated), `Api-Version`, `X-Version`, `X-Version-Name`, `X-Nc-Client-Ip`, `Business-Process-Id`, `Originating-Bi-Id`, configurable custom headers.
+- **`spring-context-aggregator`** — Spring `HandlerInterceptor` (inbound) + `ClientHttpRequestInterceptor`/Kafka/Rabbit interceptors (outbound).
+- **`context-propagation-test-extensions`** — JUnit 5 test utilities (Jandex index rebuilder).
+- **`context-propagation-bom`** — BOM for consumers.
+- **`api-tests`**, **`sample-context-tests`** — integration/API compatibility test suites.
+- **`context-propagation-report-aggregate`** — JaCoCo aggregate.
+
+## Build
+
+```bash
+mvn verify                  # full build including api-tests and sample-context-tests
+mvn generate-sources        # rebuild Jandex index after adding a new provider
+```
+
+## Architecture
+
+1. **Provider discovery via Jandex** — not classpath reflection. Jandex index must be regenerated (`mvn generate-sources`) after adding a new provider class, otherwise it won't be picked up at runtime.
+2. **Storage strategies**: default `ThreadLocal`; use `ThreadLocalWithInheritance` when submitting tasks to child threads.
+3. **Async propagation**: wrap `ExecutorService` with the provided wrapper, or capture a `ContextSnapshot` and restore it inside the `Callable`/`Supplier`.
+4. **Serialisation**: snapshots are JSON-serialised for async messaging hand-off.
+
+## Extension Guide
+
+- New built-in context → add a `ContextProvider` implementation in `framework-contexts/src/main/java/`, annotate it for Jandex, then run `mvn generate-sources`.
+- New Spring interceptor → add to `spring-context-aggregator`.

core-context-propagation/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-error-handling/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md — core-error-handling
+
+## Module
+
+Exception hierarchy based on numeric error codes, plus REST layer mapping to RFC-compliant problem JSON.
+
+## Sub-modules
+
+- **`core-error-handling-runtime`** — base `ErrorCodeException`, `ErrorCode` contract, `MultiCauseException`.
+- **`core-error-handling-rest`** — `@ControllerAdvice` / `@ExceptionHandler` that maps `ErrorCodeException` to problem JSON responses.
+- **`core-error-handling-report-aggregate`** — JaCoCo aggregate; not a shipping artifact.
+
+## Build
+
+```bash
+mvn verify
+```
+
+## Key Pattern
+
+All application exceptions must extend `ErrorCodeException` and supply an `ErrorCode`. The REST handler in `core-error-handling-rest` serialises them automatically — do not add ad-hoc `@ExceptionHandler` methods for error-coded exceptions in service code.
+
+## Extension Guide
+
+- New error code → implement `ErrorCode` interface in `core-error-handling-runtime`.
+- New HTTP mapping rule → add to the `@ControllerAdvice` in `core-error-handling-rest`.

core-error-handling/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-junit-k8s-extension/AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md — core-junit-k8s-extension
+
+## Module
+
+JUnit 5 extension wiring Kubernetes infrastructure into integration/smoke tests: Fabric8 client injection, automatic port-forwarding, pod scaling, multi-cloud configuration.
+
+## Sub-modules
+
+- **`cloud-core-extension`** — the extension implementation.
+- **`cloud-core-extension-bom`** — BOM for consumers.
+
+## Build
+
+```bash
+mvn verify -DskipTests      # compile only; no cluster needed
+# Full integration run requires Kubernetes 1.27+ (real cluster, Kind, or Minikube)
+```
+
+## Key Annotations
+
+| Annotation | Effect |
+|---|---|
+| `@EnableExtension` | Activates the extension on a test class |
+| `@SmokeTest` | Marks a test as a smoke/integration test (filtered in CI) |
+| `@PortForward` | Requests port-forwarding to a pod/service before the test method |
+| `@Cloud` | Selects the target cloud environment |
+
+## Extension Guide
+
+- New annotation → add to `cloud-core-extension/src/main/java/`; register the JUnit 5 callback in the extension class.
+- Timeouts, retry counts, and watch durations are configured via JVM system properties at test runtime — see `cloud-core-extension/README.md` for the full property list.
+
+## Notes
+
+- Requires Java 21+ and valid `KUBECONFIG` or in-cluster credentials at test runtime.

core-junit-k8s-extension/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-microservice-dependencies/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md — core-microservice-dependencies
+
+## Module
+
+Produces `cloud-core-java-bom` — the central Bill of Materials pinning dependency versions for the entire platform. POM-only, no Java source.
+
+## Build
+
+```bash
+mvn install       # installs BOM to local repo
+```
+
+## Usage in Consumers
+
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>com.netcracker.cloud</groupId>
+      <artifactId>cloud-core-java-bom</artifactId>
+      <version>${cloud-core-java-bom.version}</version>
+      <type>pom</type>
+      <scope>import</scope>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+```
+
+## Extension Guide
+
+- Bumping a transitive library version platform-wide → change it in `cloud-core-java-bom/pom.xml`.
+- Adding a library used by 2+ modules → declare it here; consuming modules omit the `<version>` tag.
+
+## Notes
+
+- No Java source code belongs here.

core-microservice-dependencies/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-microservice-framework-extensions/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md — core-microservice-framework-extensions
+
+## Module
+
+Optional add-ons for `core-microservice-framework`: SpringDoc/OpenAPI, health indicators, and Micrometer metrics.
+
+## Sub-modules
+
+- **`framework-extension-springdoc-swagger`** — SpringDoc/OpenAPI 3 Swagger UI integration.
+- **`framework-extension-health-indicators`** — custom Spring Boot health indicator beans.
+- **`framework-extension-metrics`** — Micrometer metrics extensions.
+- **`framework-extensions-parent`** — shared build POM.
+- **`framework-extension-bom`** — BOM for consumers.
+- **`framework-extensions-report-aggregate`** — JaCoCo aggregate.
+
+## Build
+
+```bash
+mvn verify
+```
+
+## Extension Guide
+
+- New OpenAPI customisation → add to `framework-extension-springdoc-swagger`.
+- New health indicator → add to `framework-extension-health-indicators`; implement Spring Boot's `HealthIndicator`.
+- New metric → add to `framework-extension-metrics`; register via Micrometer `MeterRegistry`.
+- New extension artifact → create sub-module, add to `framework-extensions-parent` modules list and `framework-extension-bom`.

core-microservice-framework-extensions/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

core-microservice-framework/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md — core-microservice-framework
+
+## Module
+
+Spring Boot scaffolding providing out-of-the-box microservice capabilities: route registration, config-server integration, security policy, M2M / user-secured REST clients, header interceptors, and DBaaS integration.
+
+## Sub-modules
+
+- **`microservice-framework-common`** — shared Spring utilities, `MicroserviceApplicationContext`, property loaders.
+- **`microservice-framework-webclient`** — **preferred** RestClient implementation based on Spring WebClient.
+- **`microservice-framework-resttemplate`** — **deprecated** RestTemplate-based RestClient. No new development.
+- **`microservice-framework-parent`** — shared POM (no code).
+- **`microservice-framework-report-aggregate`** — JaCoCo aggregate.
+
+## Build
+
+```bash
+mvn verify          # PMD analysis runs automatically during verify; violations fail the build
+```
+
+## Entry Points
+
+- `MicroserviceApplicationBuilder` — fluent builder wiring all framework features into a Spring `ApplicationContext`.
+- `MicroserviceApplicationContext` — extended `ApplicationContext` exposing framework-managed beans.
+
+## Extension Guide
+
+- New feature → add to `microservice-framework-webclient` (never to `resttemplate`).
+- New shared Spring utility → add to `microservice-framework-common`.
+
+## Notes
+
+- Always depend on `microservice-framework-webclient`, never on `microservice-framework-resttemplate` in new development.
+- PMD rules are configured in `microservice-framework-parent`; violations fail the build.

core-microservice-framework/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md