From 5a6cb419d1cbb0e5359cb384f02df887a8892726 Mon Sep 17 00:00:00 2001 From: iglin Date: Thu, 30 Apr 2026 17:30:13 +0500 Subject: [PATCH 1/2] doc: add claude initial files --- AGENTS.md | 79 +++++++++++++++++++ CLAUDE.md | 1 + .../AGENTS.md | 20 +++++ .../CLAUDE.md | 1 + core-blue-green-state-monitor/AGENTS.md | 29 +++++++ core-blue-green-state-monitor/CLAUDE.md | 1 + core-context-propagation-quarkus/AGENTS.md | 30 +++++++ core-context-propagation-quarkus/CLAUDE.md | 1 + core-context-propagation/AGENTS.md | 34 ++++++++ core-context-propagation/CLAUDE.md | 1 + core-error-handling/AGENTS.md | 26 ++++++ core-error-handling/CLAUDE.md | 1 + core-junit-k8s-extension/AGENTS.md | 35 ++++++++ core-junit-k8s-extension/CLAUDE.md | 1 + core-microservice-dependencies/AGENTS.md | 36 +++++++++ core-microservice-dependencies/CLAUDE.md | 1 + .../AGENTS.md | 27 +++++++ .../CLAUDE.md | 1 + core-microservice-framework/AGENTS.md | 34 ++++++++ core-microservice-framework/CLAUDE.md | 1 + core-mongo-evolution/AGENTS.md | 32 ++++++++ core-mongo-evolution/CLAUDE.md | 1 + core-process-orchestrator/AGENTS.md | 32 ++++++++ core-process-orchestrator/CLAUDE.md | 1 + core-quarkus-extensions/AGENTS.md | 37 +++++++++ core-quarkus-extensions/CLAUDE.md | 1 + core-rest-libraries/AGENTS.md | 39 +++++++++ core-rest-libraries/CLAUDE.md | 1 + core-restclient/AGENTS.md | 30 +++++++ core-restclient/CLAUDE.md | 1 + core-springboot-starter/AGENTS.md | 16 ++++ core-springboot-starter/CLAUDE.md | 1 + core-utils/AGENTS.md | 27 +++++++ core-utils/CLAUDE.md | 1 + dbaas-client/AGENTS.md | 41 ++++++++++ dbaas-client/CLAUDE.md | 1 + maas-client-quarkus/AGENTS.md | 28 +++++++ maas-client-quarkus/CLAUDE.md | 1 + maas-client-spring/AGENTS.md | 30 +++++++ maas-client-spring/CLAUDE.md | 1 + maas-client/AGENTS.md | 36 +++++++++ maas-client/CLAUDE.md | 1 + maas-declarative-client-commons/AGENTS.md | 30 +++++++ maas-declarative-client-commons/CLAUDE.md | 1 + maas-declarative-client-quarkus/AGENTS.md | 25 ++++++ maas-declarative-client-quarkus/CLAUDE.md | 1 + maas-declarative-client-spring/AGENTS.md | 20 +++++ maas-declarative-client-spring/CLAUDE.md | 1 + 48 files changed, 797 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 core-blue-green-state-monitor-quarkus/AGENTS.md create mode 100644 core-blue-green-state-monitor-quarkus/CLAUDE.md create mode 100644 core-blue-green-state-monitor/AGENTS.md create mode 100644 core-blue-green-state-monitor/CLAUDE.md create mode 100644 core-context-propagation-quarkus/AGENTS.md create mode 100644 core-context-propagation-quarkus/CLAUDE.md create mode 100644 core-context-propagation/AGENTS.md create mode 100644 core-context-propagation/CLAUDE.md create mode 100644 core-error-handling/AGENTS.md create mode 100644 core-error-handling/CLAUDE.md create mode 100644 core-junit-k8s-extension/AGENTS.md create mode 100644 core-junit-k8s-extension/CLAUDE.md create mode 100644 core-microservice-dependencies/AGENTS.md create mode 100644 core-microservice-dependencies/CLAUDE.md create mode 100644 core-microservice-framework-extensions/AGENTS.md create mode 100644 core-microservice-framework-extensions/CLAUDE.md create mode 100644 core-microservice-framework/AGENTS.md create mode 100644 core-microservice-framework/CLAUDE.md create mode 100644 core-mongo-evolution/AGENTS.md create mode 100644 core-mongo-evolution/CLAUDE.md create mode 100644 core-process-orchestrator/AGENTS.md create mode 100644 core-process-orchestrator/CLAUDE.md create mode 100644 core-quarkus-extensions/AGENTS.md create mode 100644 core-quarkus-extensions/CLAUDE.md create mode 100644 core-rest-libraries/AGENTS.md create mode 100644 core-rest-libraries/CLAUDE.md create mode 100644 core-restclient/AGENTS.md create mode 100644 core-restclient/CLAUDE.md create mode 100644 core-springboot-starter/AGENTS.md create mode 100644 core-springboot-starter/CLAUDE.md create mode 100644 core-utils/AGENTS.md create mode 100644 core-utils/CLAUDE.md create mode 100644 dbaas-client/AGENTS.md create mode 100644 dbaas-client/CLAUDE.md create mode 100644 maas-client-quarkus/AGENTS.md create mode 100644 maas-client-quarkus/CLAUDE.md create mode 100644 maas-client-spring/AGENTS.md create mode 100644 maas-client-spring/CLAUDE.md create mode 100644 maas-client/AGENTS.md create mode 100644 maas-client/CLAUDE.md create mode 100644 maas-declarative-client-commons/AGENTS.md create mode 100644 maas-declarative-client-commons/CLAUDE.md create mode 100644 maas-declarative-client-quarkus/AGENTS.md create mode 100644 maas-declarative-client-quarkus/CLAUDE.md create mode 100644 maas-declarative-client-spring/AGENTS.md create mode 100644 maas-declarative-client-spring/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..4c454430e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,79 @@ +# 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 +mvn verify -T 1C # full parallel build + tests +mvn verify -pl -am # module + its transitive deps from root +mvn verify # from a module directory +mvn test -Dtest=ClassName # single test class +mvn test -Dtest=ClassName#methodName # single test method +mvn verify -DskipTests # compile only, skip tests +mvn deploy -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 + +- Add any library used by 2+ modules to `core-microservice-dependencies/cloud-core-java-bom/pom.xml` +- New Quarkus extensions must also be registered in `core-quarkus-extensions/cloud-core-quarkus-bom/pom.xml` +- New modules inherit from the nearest `*-parent` POM and import `cloud-core-java-bom` via `` + +## 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**: import `cloud-core-java-bom` in `` before adding deps to any new module +- **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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-blue-green-state-monitor-quarkus/AGENTS.md b/core-blue-green-state-monitor-quarkus/AGENTS.md new file mode 100644 index 000000000..24cd53abd --- /dev/null +++ b/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 + +- Quarkus version: 3.33.1. diff --git a/core-blue-green-state-monitor-quarkus/CLAUDE.md b/core-blue-green-state-monitor-quarkus/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-blue-green-state-monitor-quarkus/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-blue-green-state-monitor/AGENTS.md b/core-blue-green-state-monitor/AGENTS.md new file mode 100644 index 000000000..96b201965 --- /dev/null +++ b/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 # requires Docker (Testcontainers + real Consul) +mvn verify -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`. diff --git a/core-blue-green-state-monitor/CLAUDE.md b/core-blue-green-state-monitor/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-blue-green-state-monitor/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-context-propagation-quarkus/AGENTS.md b/core-context-propagation-quarkus/AGENTS.md new file mode 100644 index 000000000..fe83069a1 --- /dev/null +++ b/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 + +- Quarkus version: 3.33.1. CDI (Arc) producers only — no Spring annotations. diff --git a/core-context-propagation-quarkus/CLAUDE.md b/core-context-propagation-quarkus/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-context-propagation-quarkus/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-context-propagation/AGENTS.md b/core-context-propagation/AGENTS.md new file mode 100644 index 000000000..41974301c --- /dev/null +++ b/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`. diff --git a/core-context-propagation/CLAUDE.md b/core-context-propagation/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-context-propagation/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-error-handling/AGENTS.md b/core-error-handling/AGENTS.md new file mode 100644 index 000000000..8926169ba --- /dev/null +++ b/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`. diff --git a/core-error-handling/CLAUDE.md b/core-error-handling/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-error-handling/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-junit-k8s-extension/AGENTS.md b/core-junit-k8s-extension/AGENTS.md new file mode 100644 index 000000000..9836ac237 --- /dev/null +++ b/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. diff --git a/core-junit-k8s-extension/CLAUDE.md b/core-junit-k8s-extension/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-junit-k8s-extension/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-microservice-dependencies/AGENTS.md b/core-microservice-dependencies/AGENTS.md new file mode 100644 index 000000000..8d2a0ba9b --- /dev/null +++ b/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 + + + + com.netcracker.cloud + cloud-core-java-bom + ${cloud-core-java-bom.version} + pom + import + + + +``` + +## 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 `` tag. + +## Notes + +- No Java source code belongs here. diff --git a/core-microservice-dependencies/CLAUDE.md b/core-microservice-dependencies/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-microservice-dependencies/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-microservice-framework-extensions/AGENTS.md b/core-microservice-framework-extensions/AGENTS.md new file mode 100644 index 000000000..6a0c2cfad --- /dev/null +++ b/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`. diff --git a/core-microservice-framework-extensions/CLAUDE.md b/core-microservice-framework-extensions/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-microservice-framework-extensions/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-microservice-framework/AGENTS.md b/core-microservice-framework/AGENTS.md new file mode 100644 index 000000000..e210fb40c --- /dev/null +++ b/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. diff --git a/core-microservice-framework/CLAUDE.md b/core-microservice-framework/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-microservice-framework/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-mongo-evolution/AGENTS.md b/core-mongo-evolution/AGENTS.md new file mode 100644 index 000000000..07708bdb0 --- /dev/null +++ b/core-mongo-evolution/AGENTS.md @@ -0,0 +1,32 @@ +# AGENTS.md — core-mongo-evolution + +## Module + +MongoDB schema migration tool. Scans `@ChangeLog`-annotated classes, tracks applied versions in a dedicated collection, and applies pending migrations on startup (analogous to Flyway/Liquibase for MongoDB). + +## Sub-modules + +- **`mongo-evolution-java`** — pure Java implementation using `mongodb-driver-sync` 4.x; no Spring dependency. +- **`mongo-evolution-spring`** — Spring Boot auto-configuration wrapping the Java core with `MongoTemplate` support. +- **`mongo-evolution-report-aggregate`** — JaCoCo aggregate. + +## Build + +```bash +mvn verify +``` + +## Key Pattern + +1. Annotate a class with `@ChangeLog(order = N)`. +2. Annotate migration methods with `@ChangeSet(order = "NNN", id = "unique-id", author = "name")`. +3. `MongoEvolution` / `SpringMongoEvolution` discovers and executes them in order, recording applied IDs. + +## Extension Guide + +- New migration → new `@ChangeLog` class or new `@ChangeSet` method in an existing one. IDs must be globally unique and must never be reused. +- Do not reorder or delete already-executed `@ChangeSet` entries — applied IDs are recorded in the DB. + +## Notes + +- Uses `mongodb-driver-sync` 4.x; `MongoCollection.find()` return types differ from 3.x. diff --git a/core-mongo-evolution/CLAUDE.md b/core-mongo-evolution/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-mongo-evolution/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-process-orchestrator/AGENTS.md b/core-process-orchestrator/AGENTS.md new file mode 100644 index 000000000..d77df0433 --- /dev/null +++ b/core-process-orchestrator/AGENTS.md @@ -0,0 +1,32 @@ +# AGENTS.md — core-process-orchestrator + +## Module + +Persistent, dependency-aware task scheduling and execution framework. Tasks and states are stored in a relational database via `db-scheduler` so they survive process restarts. + +## Build + +```bash +mvn verify +``` + +## Architecture + +- **`ProcessDefinition`** — declares a set of named tasks and their dependency edges (DAG). +- **`ProcessOrchestrator`** — entry point: submits a `ProcessDefinition`, drives execution respecting dependencies, handles timeouts. +- **`TaskExecutorService`** — pluggable interface; implementations provide actual business logic. +- Persistence: HikariCP 7.0.2 + `db-scheduler` 16.7.1. Task payloads serialised with Jackson 2.21.2. + +## Key Dependencies + +- `db-scheduler` 16.7.1, HikariCP 7.0.2, Jackson 2.21.2 +- Tests: JUnit Jupiter 6.0.3, Awaitility 4.3.0 + +## Extension Guide + +- New task type → implement `TaskExecutorService`, register in `ProcessDefinition`. +- Task payloads must be Jackson-serialisable (needed for persistence and restart recovery). + +## Notes + +- No Spring/Quarkus dependency — deliberately framework-agnostic. diff --git a/core-process-orchestrator/CLAUDE.md b/core-process-orchestrator/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-process-orchestrator/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-quarkus-extensions/AGENTS.md b/core-quarkus-extensions/AGENTS.md new file mode 100644 index 000000000..b400a6d4d --- /dev/null +++ b/core-quarkus-extensions/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md — core-quarkus-extensions + +## Module + +Quarkus extensions mirroring the Spring functionality in `core-microservice-framework` and related modules. + +## Sub-modules + +| Sub-module | Spring counterpart | +|---|---| +| `context` | `core-context-propagation` Spring modules | +| `security` | `core-rest-libraries/security` | +| `log-manager` | `core-rest-libraries/log-manager` | +| `config-sources` | `core-rest-libraries/config-server-loader` + `consul-config-provider` | +| `dbaas-client` | `dbaas-client` Spring starters | +| `routes-registrator` | `core-rest-libraries/route-registration` | +| `maas-client` | `maas-client-spring` | +| `stomp-ws-server` | (no Spring equivalent) | +| `rest-api-deprecation-switcher` | `core-rest-libraries/rest-api-deprecation-switcher` | +| `cloud-core-quarkus-bom` | BOM for consumers | +| `build-parent` | Shared build POM | +| `report-aggregate` | JaCoCo aggregate | + +## Build + +```bash +mvn verify +``` + +## Extension Guide + +- New extension → create sub-module, register it in `cloud-core-quarkus-bom/pom.xml` so consumers can import without specifying a version. +- CDI (Arc) producers only — no Spring annotations. + +## Notes + +- Quarkus version: 3.33.1. diff --git a/core-quarkus-extensions/CLAUDE.md b/core-quarkus-extensions/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-quarkus-extensions/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-rest-libraries/AGENTS.md b/core-rest-libraries/AGENTS.md new file mode 100644 index 000000000..538bdc1a7 --- /dev/null +++ b/core-rest-libraries/AGENTS.md @@ -0,0 +1,39 @@ +# AGENTS.md — core-rest-libraries + +## Module + +Collection of REST-layer utilities consumed by `core-microservice-framework` and services directly. + +## Sub-modules + +| Sub-module | Contents | +|---|---| +| `webclient` | Spring WebClient builder helpers, timeout/retry config (`SmartWebClient`, `@EnableFrameworkWebClient`) | +| `restlegacy` | Legacy RestTemplate helpers — no new code | +| `route-registration` | Dynamic route registration (`@Routes`, `@Route` annotations) | +| `config-server-loader` | Loads properties from Spring Cloud Config Server at startup (`@EnableConfigServerLoaderOnWebClient`) | +| `consul-config-provider` | Consul KV-based `PropertySource` | +| `rest-api-deprecation-switcher` | Request-based toggle for deprecated API endpoints | +| `log-manager` | Structured JSON logging configuration | +| `security` | JWT parsing, RBAC helpers, security filter beans | +| `rest-third-party` | Thin wrappers over external REST clients | +| `rest-libraries-bom` | BOM for consumers | +| `rest-libraries-parent` | Shared POM | +| `report-aggregate` | JaCoCo aggregate | + +## Build + +```bash +mvn verify +``` + +## Extension Guide + +- New WebClient feature → add to `webclient`; use `TlsUtils` from `core-utils` for any TLS setup. +- New route annotation → add to `route-registration`. +- New security utility → add to `security`. + +## Notes + +- `restlegacy` receives no new development — use `webclient` sub-module. +- Depends on `core-utils` for TLS; do not re-implement TLS logic here. diff --git a/core-rest-libraries/CLAUDE.md b/core-rest-libraries/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-rest-libraries/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-restclient/AGENTS.md b/core-restclient/AGENTS.md new file mode 100644 index 000000000..e9b9a962a --- /dev/null +++ b/core-restclient/AGENTS.md @@ -0,0 +1,30 @@ +# AGENTS.md — core-restclient + +## Module + +API abstraction over HTTP client implementations so callers are decoupled from WebClient/RestTemplate internals. + +## Sub-modules + +- **`microservice-restclient-api`** — interfaces and request/response DTOs (no implementation). +- **`microservice-restclient-webclient`** — **preferred** WebClient-backed implementation. +- **`microservice-restclient-resttemplate`** — **deprecated** RestTemplate-backed implementation; no new development. +- **`microservice-restclient-test-utils`** — mock implementations and helpers for unit tests. +- **`parent`** — shared POM. +- **`microservice-restclient-report-aggregate`** — JaCoCo aggregate. + +## Build + +```bash +mvn verify +``` + +## Extension Guide + +- New HTTP feature → add interface to `microservice-restclient-api`, implement in `microservice-restclient-webclient`. +- Add test helpers for new features to `microservice-restclient-test-utils`. + +## Notes + +- Test code should depend on `microservice-restclient-test-utils` rather than Mockito-mocking the API interfaces directly. +- `microservice-restclient-resttemplate` receives no new development. diff --git a/core-restclient/CLAUDE.md b/core-restclient/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-restclient/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-springboot-starter/AGENTS.md b/core-springboot-starter/AGENTS.md new file mode 100644 index 000000000..905a31571 --- /dev/null +++ b/core-springboot-starter/AGENTS.md @@ -0,0 +1,16 @@ +# AGENTS.md — core-springboot-starter + +## Module + +Parent POM for Spring Boot microservices. POM-only, no Java source. Inherits from `spring-boot-starter-parent` (v4.0.5), imports `cloud-core-java-bom`, and pulls in all `core-microservice-framework` artifacts as managed dependencies. + +## Build + +```bash +mvn install # installs the POM to local repo for use by dependent services +``` + +## Extension Guide + +- Version bumps to `spring-boot-starter-parent` here ripple to all consumer services — verify downstream compatibility before changing. +- Do not add Java source code here. diff --git a/core-springboot-starter/CLAUDE.md b/core-springboot-starter/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-springboot-starter/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/core-utils/AGENTS.md b/core-utils/AGENTS.md new file mode 100644 index 000000000..649e8e5db --- /dev/null +++ b/core-utils/AGENTS.md @@ -0,0 +1,27 @@ +# AGENTS.md — core-utils + +## Module + +Low-level utilities for TLS configuration and Kubernetes projected-volume token handling. No Spring or Quarkus dependency; purely plain Java 21. + +## Sub-modules + +- **`tls`** — `TlsConfig` (interface), `TlsUtils`, `DefaultTlsConfig`: build `SSLContext` from PEM/JKS; detect mTLS setup. +- **`k8s`** — `KubernetesAudienceToken`, `KubernetesTokenVerifier`, `TokenSource`: read and verify Kubernetes service-account projected tokens. + +## Build + +```bash +mvn verify # from this directory +mvn verify -pl core-utils -am # from repo root (includes transitive build) +``` + +## Extension Guide + +- New TLS helper → add to `tls/src/main/java/`. +- New K8s token utility → add to `k8s/src/main/java/`. +- No framework imports allowed; keep plain Java 21. + +## Notes + +- TLS utilities are consumed upstream by `core-rest-libraries` and `dbaas-client` — avoid breaking API changes. diff --git a/core-utils/CLAUDE.md b/core-utils/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/core-utils/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/dbaas-client/AGENTS.md b/dbaas-client/AGENTS.md new file mode 100644 index 000000000..5f355fa43 --- /dev/null +++ b/dbaas-client/AGENTS.md @@ -0,0 +1,41 @@ +# AGENTS.md — dbaas-client + +## Module + +Database-as-a-Service client. Obtains connection strings and credentials from the `dbaas-agent` sidecar (default `http://dbaas-agent:8080`) so services never hold static DB credentials. + +## Sub-modules + +``` +dbaas-client-java/ + ├── dbaas-client-postgres-starter # PostgreSQL DataSource via DBaaS + ├── dbaas-client-mongo-starter # MongoDB MongoClient via DBaaS + ├── dbaas-client-cassandra-starter # Cassandra CqlSession via DBaaS + ├── dbaas-client-opensearch-starter # OpenSearch RestClient via DBaaS + ├── dbaas-client-clickhouse-starter # ClickHouse client via DBaaS + ├── dbaas-client-arangodb-starter # ArangoDB client via DBaaS + └── dbaas-client-redis-starter # Redis client via DBaaS +dbaas-client-bom-parent/ # BOM +dbaas-client-parent/ # shared build POM +dbaas-client-report-aggregate/ # JaCoCo aggregate +``` + +## Build + +```bash +mvn verify # requires Docker (Testcontainers) +mvn verify -DskipTests # skip integration tests when Docker is unavailable +``` + +## Configuration + +Agent address via `application.yml` property `dbaas.api.url` (default `http://dbaas-agent:8080`). + +## Extension Guide + +- New database type → add `*-base` + `*-starter` sub-modules under `dbaas-client-java/`, register both in `dbaas-client-java/pom.xml` and in the BOM. +- Each starter must use `@ConditionalOnClass` so it auto-configures only when the driver is on the classpath. + +## Notes + +- Do not hardcode database credentials — all credentials must flow through the DBaaS agent response. diff --git a/dbaas-client/CLAUDE.md b/dbaas-client/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/dbaas-client/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/maas-client-quarkus/AGENTS.md b/maas-client-quarkus/AGENTS.md new file mode 100644 index 000000000..09a7a5161 --- /dev/null +++ b/maas-client-quarkus/AGENTS.md @@ -0,0 +1,28 @@ +# AGENTS.md — maas-client-quarkus + +## Module + +Quarkus CDI integration of `maas-client` core. Provides Arc producers for `MaaSAPIClient` and SmallRye Reactive Messaging interceptors for context propagation and blue/green pause on Kafka and RabbitMQ channels. + +## Sub-modules + +- **`maas-client-quarkus-common`** — shared Arc producers and configuration. +- **`maas-client-quarkus-kafka`** — Kafka channel interceptors. +- **`maas-client-quarkus-rabbit`** — RabbitMQ channel interceptors. +- **`maas-client-quarkus-bom`** — BOM for consumers. +- **`maas-client-quarkus-report-aggregate`** — JaCoCo aggregate. + +## Build + +```bash +mvn verify +``` + +## Extension Guide + +- Core/framework-agnostic logic lives in `maas-client` — do not duplicate it here. +- New CDI producer → add to `maas-client-quarkus-common` using Arc `@Produces`. + +## Notes + +- Quarkus version: 3.33.1. diff --git a/maas-client-quarkus/CLAUDE.md b/maas-client-quarkus/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/maas-client-quarkus/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/maas-client-spring/AGENTS.md b/maas-client-spring/AGENTS.md new file mode 100644 index 000000000..f816fb0f8 --- /dev/null +++ b/maas-client-spring/AGENTS.md @@ -0,0 +1,30 @@ +# AGENTS.md — maas-client-spring + +## Module + +Spring Boot auto-configuration wrapping `maas-client` core for Kafka and RabbitMQ. + +## Sub-modules + +- **`maas-client-spring`** — Spring Boot starter: auto-configures `MaaSAPIClient` bean. +- **`maas-client-spring-kafka`** — Spring Kafka listener container factory with context propagation and blue/green pause. +- **`maas-client-spring-rabbit`** — Spring AMQP listener container factory with equivalent features. +- **`maas-client-spring-report-aggregate`** — JaCoCo aggregate. + +## Build + +```bash +mvn verify +``` + +## Key Dependencies + +- Spring Boot 4.0.5, Spring Cloud 2025.1.1 +- Lombok (delombok sources generated at build time by `lombok-maven-plugin`) + +## Extension Guide + +- New Spring-specific MaaS feature → add to `maas-client-spring`. +- New Kafka integration → add to `maas-client-spring-kafka`. +- New RabbitMQ integration → add to `maas-client-spring-rabbit`. +- Core (framework-agnostic) logic belongs in `maas-client`, not here. diff --git a/maas-client-spring/CLAUDE.md b/maas-client-spring/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/maas-client-spring/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/maas-client/AGENTS.md b/maas-client/AGENTS.md new file mode 100644 index 000000000..eb25d0be2 --- /dev/null +++ b/maas-client/AGENTS.md @@ -0,0 +1,36 @@ +# AGENTS.md — maas-client + +## Module + +Framework-agnostic core client for the Messaging-as-a-Service API. Handles topic/queue provisioning, tenant namespace management, and wires context propagation into Kafka and RabbitMQ messages. + +## Sub-modules + +| Sub-module | Purpose | +|---|---| +| `client` | `MaaSAPIClient` / `MaaSAPIClientImpl` — HTTP calls to MaaS control plane | +| `kafka-context-propagation` | Injects/extracts `ContextSnapshot` from Kafka message headers | +| `kafka-blue-green-consumer` | Kafka consumer that pauses during blue/green flips | +| `kafka-streams-adapter` | Kafka Streams `Processor` wrapper with context propagation | +| `rabbit-context-propagation` | Injects/extracts context from `AMQP.BasicProperties` | +| `rabbit-blue-green` | RabbitMQ consumer pause for blue/green flips | +| `deployment-version-tracker` | Tracks current deployment version for blue/green routing | +| `bom` | BOM for consumers | +| `report-aggregate` | JaCoCo aggregate | + +## Build + +```bash +mvn verify +``` + +## Architecture + +- No Spring or Quarkus dependency — pure Java. Framework integrations live in `maas-client-spring` and `maas-client-quarkus`. +- Context propagation delegates to `core-context-propagation` for snapshot capture/restore. +- Blue/green-aware consumers delegate to `core-blue-green-state-monitor` for state detection. + +## Extension Guide + +- New messaging protocol → add `*-context-propagation` + `*-blue-green` sub-modules; keep them framework-agnostic. +- New MaaS API endpoint → extend `MaaSAPIClient` interface in `client`, implement in `MaaSAPIClientImpl`. diff --git a/maas-client/CLAUDE.md b/maas-client/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/maas-client/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/maas-declarative-client-commons/AGENTS.md b/maas-declarative-client-commons/AGENTS.md new file mode 100644 index 000000000..601eec443 --- /dev/null +++ b/maas-declarative-client-commons/AGENTS.md @@ -0,0 +1,30 @@ +# AGENTS.md — maas-declarative-client-commons + +## Module + +Shared utilities for annotation-driven (declarative) Kafka client configuration. Primary sub-module: `maas-kafka-client`. + +## Sub-modules + +- **`maas-kafka-client`** — annotation processor, declarative Kafka producer/consumer wiring, MaaS topic resolution. + +## Build + +```bash +mvn verify # integration tests require Docker (Testcontainers + real Kafka) +mvn verify -DskipTests # compile and unit tests only +``` + +## Key Dependencies + +- `kafka-clients` 4.2.0 +- Tests: Mockito 5.21.0, AssertJ 3.27.7, Testcontainers + +## Extension Guide + +- New declarative annotation → add to `maas-kafka-client/src/main/java/`; add processing logic in the annotation processor. +- Consumers should depend on `maas-declarative-client-spring` or `maas-declarative-client-quarkus`, not this module directly. + +## Notes + +- Uses `flatten-maven-plugin` — the published POM has all version references resolved. diff --git a/maas-declarative-client-commons/CLAUDE.md b/maas-declarative-client-commons/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/maas-declarative-client-commons/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/maas-declarative-client-quarkus/AGENTS.md b/maas-declarative-client-quarkus/AGENTS.md new file mode 100644 index 000000000..4086c3153 --- /dev/null +++ b/maas-declarative-client-quarkus/AGENTS.md @@ -0,0 +1,25 @@ +# AGENTS.md — maas-declarative-client-quarkus + +## Module + +Quarkus CDI integration of the declarative Kafka client. Provides Arc-based bean registration for MaaS-managed Kafka producers and consumers. + +## Sub-modules + +- **`maas-kafka-quarkus-client`** — Arc producers and Quarkus build-time extensions for declarative Kafka. +- **`maas-kafka-quarkus-client-report-aggregate`** — JaCoCo aggregate. + +## Build + +```bash +mvn verify +``` + +## Extension Guide + +- Shared Kafka logic → add to `maas-declarative-client-commons/maas-kafka-client`. +- Quarkus-specific wiring (Arc producers, build-time extensions) → add here in `maas-kafka-quarkus-client`. + +## Notes + +- Quarkus version: 3.33.1. diff --git a/maas-declarative-client-quarkus/CLAUDE.md b/maas-declarative-client-quarkus/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/maas-declarative-client-quarkus/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/maas-declarative-client-spring/AGENTS.md b/maas-declarative-client-spring/AGENTS.md new file mode 100644 index 000000000..c8a2f435f --- /dev/null +++ b/maas-declarative-client-spring/AGENTS.md @@ -0,0 +1,20 @@ +# AGENTS.md — maas-declarative-client-spring + +## Module + +Spring Boot integration for the declarative Kafka client. Wires MaaS topic names from the MaaS control plane at startup via annotation-based consumer/producer configuration. + +## Sub-modules + +- **`maas-kafka-spring-client`** — Spring auto-configuration and bean post-processing for declarative Kafka. + +## Build + +```bash +mvn verify +``` + +## Extension Guide + +- Shared annotation logic → add to `maas-declarative-client-commons/maas-kafka-client`. +- Spring-specific glue (auto-configuration, `BeanPostProcessor`) → add here in `maas-kafka-spring-client`. diff --git a/maas-declarative-client-spring/CLAUDE.md b/maas-declarative-client-spring/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/maas-declarative-client-spring/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 4905a7cac115382cf80cf0eecf4bf0123c2436f3 Mon Sep 17 00:00:00 2001 From: iglin Date: Tue, 12 May 2026 16:25:21 +0500 Subject: [PATCH 2/2] docs: claude init fixes --- AGENTS.md | 21 ++++++++++--------- .../AGENTS.md | 2 +- core-blue-green-state-monitor/AGENTS.md | 4 ++-- core-context-propagation-quarkus/AGENTS.md | 2 +- core-quarkus-extensions/AGENTS.md | 4 ++-- maas-client-quarkus/AGENTS.md | 2 +- maas-declarative-client-quarkus/AGENTS.md | 2 +- 7 files changed, 19 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4c454430e..b438eea45 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -38,13 +38,14 @@ Java 21, groupId `com.netcracker.cloud`, distributed via GitHub Maven Packages. ## Build & Test ```bash -mvn verify -T 1C # full parallel build + tests -mvn verify -pl -am # module + its transitive deps from root -mvn verify # from a module directory -mvn test -Dtest=ClassName # single test class -mvn test -Dtest=ClassName#methodName # single test method -mvn verify -DskipTests # compile only, skip tests -mvn deploy -T 1C # build and publish to GitHub Packages +# 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 -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 @@ -56,8 +57,8 @@ mvn deploy -T 1C # build and publish to GitHub Packages ## Dependency Management -- Add any library used by 2+ modules to `core-microservice-dependencies/cloud-core-java-bom/pom.xml` -- New Quarkus extensions must also be registered in `core-quarkus-extensions/cloud-core-quarkus-bom/pom.xml` +- `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 `` ## CI / Commit Rules @@ -69,7 +70,7 @@ mvn deploy -T 1C # build and publish to GitHub Packages ## 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**: import `cloud-core-java-bom` in `` before adding deps to any new module +- **BOM hierarchy**: new Spring modules import `cloud-core-java-bom` via ``; 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 diff --git a/core-blue-green-state-monitor-quarkus/AGENTS.md b/core-blue-green-state-monitor-quarkus/AGENTS.md index 24cd53abd..f85da5e4c 100644 --- a/core-blue-green-state-monitor-quarkus/AGENTS.md +++ b/core-blue-green-state-monitor-quarkus/AGENTS.md @@ -17,4 +17,4 @@ mvn verify ## Notes -- Quarkus version: 3.33.1. +- CDI (Arc) producers only — no Spring annotations. diff --git a/core-blue-green-state-monitor/AGENTS.md b/core-blue-green-state-monitor/AGENTS.md index 96b201965..ad08f0365 100644 --- a/core-blue-green-state-monitor/AGENTS.md +++ b/core-blue-green-state-monitor/AGENTS.md @@ -13,8 +13,8 @@ Watches Consul KV for blue/green deployment state changes and provides lock mana ## Build ```bash -mvn verify # requires Docker (Testcontainers + real Consul) -mvn verify -DskipTests # skip integration tests when Docker is unavailable +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 diff --git a/core-context-propagation-quarkus/AGENTS.md b/core-context-propagation-quarkus/AGENTS.md index fe83069a1..0ff9d6241 100644 --- a/core-context-propagation-quarkus/AGENTS.md +++ b/core-context-propagation-quarkus/AGENTS.md @@ -27,4 +27,4 @@ mvn generate-sources # rebuild Jandex index after adding a new provider ## Notes -- Quarkus version: 3.33.1. CDI (Arc) producers only — no Spring annotations. +- CDI (Arc) producers only — no Spring annotations. diff --git a/core-quarkus-extensions/AGENTS.md b/core-quarkus-extensions/AGENTS.md index b400a6d4d..86e27ff6e 100644 --- a/core-quarkus-extensions/AGENTS.md +++ b/core-quarkus-extensions/AGENTS.md @@ -29,9 +29,9 @@ mvn verify ## Extension Guide -- New extension → create sub-module, register it in `cloud-core-quarkus-bom/pom.xml` so consumers can import without specifying a version. +- New extension → create sub-module, register it in `cloud-core-quarkus-bom/cloud-core-quarkus-bom-publish/pom.xml` so consumers can import without specifying a version. - CDI (Arc) producers only — no Spring annotations. ## Notes -- Quarkus version: 3.33.1. +- Quarkus version: see `quarkus.platform.version` property in `pom.xml`. diff --git a/maas-client-quarkus/AGENTS.md b/maas-client-quarkus/AGENTS.md index 09a7a5161..97af13974 100644 --- a/maas-client-quarkus/AGENTS.md +++ b/maas-client-quarkus/AGENTS.md @@ -25,4 +25,4 @@ mvn verify ## Notes -- Quarkus version: 3.33.1. +- CDI (Arc) producers only — no Spring annotations. diff --git a/maas-declarative-client-quarkus/AGENTS.md b/maas-declarative-client-quarkus/AGENTS.md index 4086c3153..0de5e4ea9 100644 --- a/maas-declarative-client-quarkus/AGENTS.md +++ b/maas-declarative-client-quarkus/AGENTS.md @@ -22,4 +22,4 @@ mvn verify ## Notes -- Quarkus version: 3.33.1. +- CDI (Arc) producers only — no Spring annotations.