bmad-method-quarkus 1.0.0

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/quarkus-hexagonal-core/SKILL.md

@@ -0,0 +1,392 @@
+---
+name: quarkus-hexagonal-core
+description: Foundation for building Java + Quarkus backend services compiled to native binaries (GraalVM/Mandrel) with strict hexagonal architecture (ports & adapters). Applies to ANY Java/Quarkus backend project — DDD bounded contexts, standalone services, internal tools alike. Use this skill whenever creating, scaffolding, reviewing, or modifying ANY Quarkus backend service, module, REST/gRPC/Kafka adapter, repository, use case, or domain entity — even if the user only says "create a service", "add an endpoint", "new microservice", or "backend project". Also the canonical source for CLASS NAMING CONVENTIONS across all layers (entities, use cases, ports, adapters, DTOs, mappers, exceptions, tests), the domain-monorepo layout (apps/, libs/, contracts/, deploy/, db/, docs/), deployable app naming ({module}-{service}-ms, tenant-agnostic), and the mandatory per-app service.yaml + README.md documentation standard — consult it whenever naming/renaming any Java class, scaffolding an app folder, or writing service docs. Enforces Java 25, JDBC-only persistence via Agroal (NO Panache, NO Hibernate/ORM), ArchUnit boundary + naming tests, and native-image compatibility. Project-specific directives (CLAUDE.md, ADRs, explicit instructions) override this standard where they conflict.
+---
+
+# Quarkus Hexagonal Core (Native-First)
+
+Foundation skill for all backend services. Other skills in this set (error-handling-i18n, kafka-messaging, openapi-tmforum, grpc-services, observability-otel) build on the structure defined here — apply this one first when scaffolding.
+
+**Scope & precedence:** these standards apply to any Java/Quarkus backend project, whether or not it is organized as DDD bounded contexts — where examples mention a BC code (`bc05`), read it as "short module/domain prefix". They are the default, not law: a project directive that says otherwise (CLAUDE.md, an ADR, an explicit user instruction) wins over this skill. When you deviate because of such a directive, follow the directive and mention which rule was overridden.
+
+## Baseline constraints (unless a project directive overrides)
+
+1. **Java 25 LTS** (`maven.compiler.release=25`). Records, sealed interfaces, pattern matching, virtual threads where blocking I/O is unavoidable.
+2. **Native binary is the delivery artifact.** Every dependency and pattern must be GraalVM/Mandrel-compatible. Build with the Mandrel container image so builds don't depend on a local GraalVM.
+3. **No ORM.** Persistence is plain JDBC through the Agroal datasource. No Panache, no Hibernate, no JPA annotations in any layer.
+4. **Domain layer has zero framework imports.** No `jakarta.*`, no `io.quarkus.*`, no Jackson annotations in `domain`. Enforced by ArchUnit.
+5. **Swagger UI only in dev/test** (see quarkus-openapi-tmforum skill).
+
+## Monorepo layout (per domain/module)
+
+One monorepo per domain (bounded context in DDD projects) holds its deployable apps plus internal libs. It never contains live environment/client configuration — the deployed state lives in the GitOps config repo.
+
+```
+/  (domain monorepo, e.g. wallet)
+├── apps/                            # deployable applications, one folder each
+│   └── wallet-backend-core-ms/
+│       ├── src/
+│       ├── pom.xml
+│       ├── Dockerfile               # this app's image build (native)
+│       ├── service.yaml             # structured metadata — JSON-Schema validated in CI
+│       └── README.md                # per-app operational doc (see "Per-app documentation")
+├── libs/                            # modules shared within the domain
+├── contracts/                       # versioned API contracts (TMF/OpenAPI, JSON Schemas, protos)
+├── deploy/                          # k8s manifests, pipelines, observability-as-code
+├── db/                              # database migrations
+├── docs/                            # architecture, ADRs, runbooks
+└── README.md                        # domain onboarding doc (see "Domain README")
+```
+
+### Deployable app naming (tenant-agnostic)
+
+```
+{module}-{service}-{type-suffix}
+```
+
+Suffixes: `-ms` (backend microservice — every Quarkus service here), `-mf` (microfrontend remote), `-module` (host/shell). Example: `wallet-backend-core-ms`. **Client and tenant never appear in app or code names** — they are runtime configuration (namespaces, labels, Helm values) applied at deploy time; the code is identical for every client and tenant.
+
+## Package layout (per service/module)
+
+```
+com.<company>.<module>          # <module> = BC code in DDD projects, service name otherwise
+├── domain/                  # PURE Java. Entities, value objects, domain events, domain services
+│   ├── model/               #   Records for VOs, sealed interfaces for events
+│   ├── event/
+│   └── exception/           #   Domain exceptions with stable error codes
+├── application/             # Use cases + ports. May use CDI annotations only (@ApplicationScoped)
+│   ├── port/
+│   │   ├── in/              #   Inbound ports (use case interfaces)
+│   │   └── out/             #   Outbound ports (repository, publisher, external service interfaces)
+│   └── usecase/             #   One class per use case, implements inbound port
+└── infrastructure/          # Adapters. All framework code lives here
+    ├── rest/                #   JAX-RS resources + DTOs + mappers (inbound adapter)
+    ├── grpc/                #   gRPC services (inbound) and clients (outbound)
+    ├── persistence/         #   JDBC repositories implementing out ports
+    ├── messaging/           #   Kafka producers/consumers, outbox
+    └── config/              #   @ConfigMapping interfaces, CDI producers
+```
+
+Rules of dependency: `infrastructure → application → domain`. Never the reverse. DTOs never leak into application/domain; map at the adapter boundary.
+
+## Class naming conventions (canonical)
+
+These names are the standard for ALL services and all sibling skills. A class name must reveal its layer and role without opening the file. Identifiers, packages, SQL objects and comments are **English only** — Spanish appears only in i18n message bundles and user-facing text (see quarkus-error-handling-i18n skill).
+
+### Domain layer (`domain`)
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Entity / aggregate root | singular noun, no suffix | `User`, `Subscription` |
+| Value object | singular noun record, no suffix | `Email`, `Money`, `Msisdn` |
+| Typed identifier | `<Entity>Id` record | `UserId`, `SubscriptionId` |
+| State enum | `<Entity>Status` | `UserStatus` |
+| Domain event | past-tense verb phrase, **no** suffix | `UserRegistered`, `SubscriptionActivated` |
+| Domain service / policy | `<Concept>Policy`, `<Concept>Calculator` | `PasswordPolicy`, `PricingCalculator` |
+| Domain exception | `<Thing><Problem>Exception` | `UserNotFoundException`, `DuplicateEmailException` |
+| Exception base | `DomainException` | |
+
+`*Service` is **never** used in the domain layer — a domain service is a policy, a calculator or a factory, and saying so beats a generic suffix.
+
+### Application layer (`application`)
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Inbound port (`port/in`) | `<Verb><Entity>UseCase` — always an interface | `RegisterUserUseCase`, `GetUserUseCase` |
+| Use case implementation (`usecase`) | `<Verb><Entity>Service` | `RegisterUserService` |
+| Command (write input) | `<Verb><Entity>Command` | `RegisterUserCommand` |
+| Query (read input) | `<Verb><Entity>Query` | `FindUsersQuery` |
+| Use case output | `<Verb><Entity>Result` | `RegisterUserResult` |
+| Outbound port — persistence | `<Entity>Repository` | `UserRepository` |
+| Outbound port — other capability | capability noun, **no technology** | `EventPublisher`, `CredentialsValidator`, `AuditRecorder` |
+
+One use case per class, one public method named after the verb (`register`, `getById`). The `*Service` suffix is **reserved** for use-case implementations in `application/usecase` (plus proto-generated gRPC stubs); it never appears on repositories, mappers or helper classes.
+
+### Infrastructure layer (`infrastructure`)
+
+**Inbound (driving) adapters — suffixed by transport:**
+
+| Adapter | Convention | Example |
+|---|---|---|
+| REST resource | `<Resource>Resource` | `UserResource`, `DigitalIdentityResource` |
+| gRPC endpoint | `<ProtoService>GrpcService` | `UserGrpcService` |
+| Kafka consumer | `<Event>Consumer` | `UserRegisteredConsumer` |
+| Scheduled job | `<Task>Job` | `OutboxRelayJob` |
+
+**Outbound (driven) adapters — prefixed by technology, keeping the port name:**
+
+| Adapter | Convention | Example |
+|---|---|---|
+| JDBC repository | `Jdbc<Port>` | `JdbcUserRepository` |
+| Outbox / Kafka publisher | `Outbox<Port>`, `Kafka<Port>` | `OutboxEventPublisher` |
+| gRPC client adapter | `Grpc<Port>` | `GrpcCredentialsValidator` |
+| REST client adapter | `Rest<Port>` | `RestPaymentGateway` |
+
+The port says *what*, the prefix says *with what* — so a second implementation (`InMemoryUserRepository` in tests) reads naturally.
+
+**Supporting classes:**
+
+| Artifact | Convention | Example |
+|---|---|---|
+| REST DTO | `<Resource>Dto`, `<Resource>CreateDto`, `<Resource>UpdateDto` | `DigitalIdentityCreateDto` |
+| Kafka payload DTO | `<Event>Payload` | `UserRegisteredPayload` |
+| Mapper | `<Entity><Transport>Mapper` | `UserRestMapper`, `UserGrpcMapper`, `UserEventMapper` |
+| Row mapper | `<Entity>RowMapper` | `UserRowMapper` |
+| Config mapping | `<Area>Config` (`@ConfigMapping` interface) | `OutboxConfig` |
+| Global handlers | `GlobalExceptionHandler`, `GrpcExceptionInterceptor` | |
+| Technical exceptions | `PersistenceException`, `TransientPersistenceException`, `PersistenceTimeoutException`, `StaleVersionException` | |
+
+The DTO ↔ domain distinction matters: `UserDto` lives in `infrastructure/rest/dto` and is what the wire sees; `User` is the domain entity. They are never the same class, even when the fields match today.
+
+### Banned and reserved names
+
+- Suffixes `*Impl`, `*Util`, `*Utils`, `*Helper`, `*Manager`, `*Handler` (the single `GlobalExceptionHandler` is the only sanctioned `*Handler`). If a class needs `Util`, it needs a real responsibility name.
+- `*DTO` / `*VO` / `*Bean` / `*POJO` in all-caps or as decoration — the standard is `*Dto`.
+- Names that shadow JDK or Jakarta types: never `ConcurrentModificationException` (use `StaleVersionException`), `Entity`, `Optional`, `Record`. An accidental `java.util` import silently changes behaviour.
+- Abbreviations that are not org-wide vocabulary (`UsrRepo`, `SubsSvc`). Module/BC codes (`bc05`) are fine in packages and config, not in class names.
+
+### Other identifiers (for reference)
+
+| Kind | Convention | Example |
+|---|---|---|
+| Deployable app | `{module}-{service}-{type}` kebab-case, tenant-agnostic (`-ms` backend) | `wallet-backend-core-ms` |
+| Package | lowercase, singular, no underscores | `com.alva.bc05.application.usecase` |
+| Constant | `UPPER_SNAKE_CASE` | `FIND_BY_ID` |
+| SQL table / column | `snake_case`, singular table | `app_user`, `created_at` |
+| Test class | `<Class>Test` (unit/`@QuarkusTest`), `<Class>IT` (`@QuarkusIntegrationTest`), `ArchitectureTest` | `JdbcUserRepositoryTest` |
+| Proto | `PascalCase` messages/services, `snake_case` fields | `GetUserRequest`, `user_id` |
+| Kafka topic / channel | see quarkus-kafka-messaging skill | `alva.bc05.user.registered.v1` |
+| Error code | `<MOD>-<HTTP>-<seq>` (`<MOD>` = short module/domain code) | `USR-404-001` |
+
+## Scaffolding checklist
+
+When creating a new service:
+
+1. App folder `apps/<module>-<service>-ms/` per the monorepo layout above.
+2. `pom.xml` with BOM `io.quarkus.platform:quarkus-bom` (latest 3.x LTS), extensions: `quarkus-rest`, `quarkus-rest-jackson`, `quarkus-agroal`, `quarkus-jdbc-postgresql`, `quarkus-arc`, `quarkus-smallrye-health`, `quarkus-flyway` (schema migrations), plus skills-specific extensions as needed.
+3. `application.properties` baseline (below).
+4. ArchUnit test (below) — add it in the same commit as the first class, not later.
+5. Native profile using Mandrel container build.
+6. `Dockerfile` at the app root, based on `quay.io/quarkus/quarkus-micro-image` (or distroless) running the native binary.
+7. `service.yaml` + per-app `README.md` (below) — in the same PR as the first endpoint, not later; CI blocks merges without them.
+
+### application.properties baseline
+
+```properties
+quarkus.datasource.db-kind=postgresql
+quarkus.datasource.jdbc.max-size=16
+quarkus.flyway.migrate-at-start=true
+
+# Native build via Mandrel container (no local GraalVM needed)
+quarkus.native.container-build=true
+quarkus.native.builder-image=mandrel
+
+quarkus.http.port=8080
+```
+
+### Maven native profile
+
+```xml
+<profile>
+  <id>native</id>
+  <activation><property><name>native</name></property></activation>
+  <properties>
+    <quarkus.native.enabled>true</quarkus.native.enabled>
+    <skipITs>false</skipITs>
+  </properties>
+</profile>
+```
+
+Build: `./mvnw package -Dnative` → binary in `target/*-runner`.
+
+## Per-app documentation (mandatory, blocking)
+
+Every deployable under `apps/<app>/` carries two files, versioned with the code and updated in the **same PR** that changes the service's behavior:
+
+- **`service.yaml`** — structured metadata validated against a JSON Schema in CI: identity (domain, system, component type, lifecycle), ownership (team, SRE, support group), criticality, tenancy (model, data isolation), runtime (type, version, ports), provided APIs with their contract files in `contracts/`, dependencies with `hard`/`soft` requirement, and the observability contract (log format, levels, required fields, data-protection rules). It feeds the service catalog and the dependency map.
+- **`README.md`** (per app) — operational doc written so a system administrator who has never seen the code can configure, deploy and recover the service. No `TBD` / "see code" (a justified `N/A` is allowed). No manual changelog section — Git keeps the history.
+
+Required `README.md` sections:
+
+1. **Identity** — app name, module (`part-of`), type (`ms`), owning team, repository, criticality, part of core yes/no
+2. **Purpose & responsibility** — description + out of scope
+3. **Tenancy model** — `shared` | `per-tenant` | `pool`; tenant identification (validated JWT claim, never a free header); data isolation; per-tenant parameters
+4. **APIs exposed** — table: api/version, protocol, route/topic, contract file, auth, visibility
+5. **Dependencies** — table: name, type, criticality (`hard`|`soft`), timeout/retry, behavior if down
+6. **Data & persistence** — engine, database/schema, tenant isolation, migrations (`db/`), cache, events
+7. **Configuration** — table: variable, description, type, required, default, varies-by (`environment`|`client`|`tenant`)
+8. **Secrets** — table: logical name, what it is, source (vault), who provides it, rotation period — **never the value**
+9. **Runtime & resources** — runtime/version, ports, requests/limits, replicas/HPA
+10. **Health checks** — liveness; readiness = **hard dependencies only**; startup probe
+11. **Deployment dependencies** — classified: startup / readiness-critical / hard runtime / soft runtime
+12. **Observability** — configurable log levels (`TRACE`–`FATAL`), the ConfigMap variable holding `logging_level`, its default, JSON log format
+13. **GitOps deployment** — location in the config repo, delivery strategy, feature flags
+14. **Rollback & recovery** — procedure, reversible migrations (N/N-1 compatible), RTO/RPO
+15. **Post-deploy validation** — smoke tests, contract tests, tenant-isolation tests
+16. **Troubleshooting** — symptom → cause → diagnosis
+
+Rule of completeness: if a variable, secret or dependency is not documented here, it does not exist — CI validates the `service.yaml` schema and the mandatory `README.md` sections as a blocking gate.
+
+### Domain README (repo root)
+
+The monorepo root `README.md` is the onboarding doc for the domain, and the owning team keeps it current:
+
+- **Identity table** — product, domain/bounded context, description, part of core, owning team, tech lead, SRE responsible, predominant criticality, predominant tenancy model, status, project, related GitOps repo.
+- **Responsibility & limits** — what the domain owns, what is explicitly out of scope, and a table of dependencies on other domains/systems (type, use, `hard`/`soft`).
+- **Deployable applications table** — one row per app: type, purpose, runtime, links to its `apps/<app>/README.md` and `service.yaml`.
+
+It never documents live environment or client configuration — the deployed state per environment/client is managed in the GitOps config repo.
+
+## Persistence pattern (JDBC + Agroal)
+
+Full standard (pool config, transactions, batches, jsonb, pagination, SQLException translation) lives in the **quarkus-sql-jdbc-agroal** skill — consult it for any repository work. Summary of the shape:
+
+Outbound port in `application/port/out`:
+
+```java
+public interface UserRepository {
+    Optional<User> findById(UserId id);
+    void save(User user);
+}
+```
+
+Adapter in `infrastructure/persistence`:
+
+```java
+@ApplicationScoped
+public class JdbcUserRepository implements UserRepository {
+
+    private final AgroalDataSource ds;
+
+    public JdbcUserRepository(AgroalDataSource ds) { this.ds = ds; }
+
+    @Override
+    public Optional<User> findById(UserId id) {
+        var sql = "SELECT id, email, status, created_at FROM app_user WHERE id = ?";
+        try (var con = ds.getConnection(); var ps = con.prepareStatement(sql)) {
+            ps.setObject(1, id.value());
+            try (var rs = ps.executeQuery()) {
+                return rs.next() ? Optional.of(mapRow(rs)) : Optional.empty();
+            }
+        } catch (SQLException e) {
+            throw new PersistenceException("user.find_by_id", e);
+        }
+    }
+    // save(): use explicit transaction control or @Transactional on the use case
+}
+```
+
+Conventions:
+- Constructor injection only (no field `@Inject`) — testable and native-friendly.
+- SQL as constants or text blocks; never string concatenation with user input.
+- Transactions: annotate the **use case** with `@Transactional` (from `quarkus-narayana-jta`) so the unit of work matches the business operation, not the repository call.
+- Row mapping by hand or a small private `mapRow(ResultSet)` — no reflection-based mappers.
+
+## Domain conventions
+
+- Value objects = records with validation in a compact constructor.
+- Entity identity = typed IDs (`record UserId(UUID value)`), never bare UUID/String in signatures.
+- Domain events = sealed interface + records, named in past tense (`UserRegistered`).
+- Domain exceptions carry a **stable error code** (used by the error-handling-i18n skill): `throw new UserNotFoundException(id)` where the exception exposes `code() -> "USR-404-001"`.
+- Naming per the canonical table above — entities and events carry no suffix, ids are `<Entity>Id`, exceptions are `<Thing><Problem>Exception`.
+
+## ArchUnit enforcement (mandatory)
+
+`src/test/java/.../ArchitectureTest.java`:
+
+```java
+@AnalyzeClasses(packages = "com.company.bc")
+class ArchitectureTest {
+
+    @ArchTest
+    static final ArchRule hexagonal = layeredArchitecture().consideringAllDependencies()
+        .layer("Domain").definedBy("..domain..")
+        .layer("Application").definedBy("..application..")
+        .layer("Infrastructure").definedBy("..infrastructure..")
+        .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Infrastructure")
+        .whereLayer("Application").mayOnlyBeAccessedByLayers("Infrastructure")
+        .whereLayer("Infrastructure").mayNotBeAccessedByAnyLayer();
+
+    @ArchTest
+    static final ArchRule domainIsPure = noClasses().that().resideInAPackage("..domain..")
+        .should().dependOnClassesThat().resideInAnyPackage(
+            "jakarta..", "io.quarkus..", "org.eclipse.microprofile..",
+            "com.fasterxml.jackson..", "io.smallrye..", "java.sql..");
+
+    @ArchTest
+    static final ArchRule noOrm = noClasses().should().dependOnClassesThat()
+        .resideInAnyPackage("jakarta.persistence..", "org.hibernate..", "io.quarkus.hibernate..");
+}
+```
+
+### Naming rules (same test class)
+
+Conventions that are not enforced decay within two sprints. Add these alongside the layer rules — `resideInAPackage` is statically imported from `JavaClass.Predicates`:
+
+```java
+@ArchTest
+static final ArchRule inboundPorts = classes().that().resideInAPackage("..application.port.in..")
+    .should().beInterfaces()
+    .andShould().haveSimpleNameEndingWith("UseCase");
+
+@ArchTest
+static final ArchRule outboundPorts = classes().that().resideInAPackage("..application.port.out..")
+    .should().beInterfaces();
+
+@ArchTest
+static final ArchRule useCaseImpls = classes().that().resideInAPackage("..application.usecase..")
+    .should().haveSimpleNameEndingWith("Service")
+    .andShould().implement(resideInAPackage("..application.port.in.."));
+
+@ArchTest
+static final ArchRule serviceSuffixIsReserved = classes().that().haveSimpleNameEndingWith("Service")
+    .should().resideInAnyPackage("..application.usecase..", "..infrastructure.grpc..");
+
+@ArchTest
+static final ArchRule restResources = classes().that().areAnnotatedWith(Path.class)
+    .should().haveSimpleNameEndingWith("Resource")
+    .andShould().resideInAPackage("..infrastructure.rest..");
+
+@ArchTest
+static final ArchRule jdbcAdapters = classes().that().resideInAPackage("..infrastructure.persistence..")
+    .and().implement(resideInAPackage("..application.port.out.."))
+    .should().haveSimpleNameStartingWith("Jdbc");
+
+@ArchTest
+static final ArchRule dtosStayInAdapters = classes().that().haveSimpleNameEndingWith("Dto")
+    .should().resideInAPackage("..infrastructure..");
+
+@ArchTest
+static final ArchRule domainExceptions = classes().that().areAssignableTo(DomainException.class)
+    .should().haveSimpleNameEndingWith("Exception")
+    .andShould().resideInAPackage("..domain.exception..");
+
+@ArchTest
+static final ArchRule bannedSuffixes = noClasses().should().haveSimpleNameEndingWith("Impl")
+    .orShould().haveSimpleNameEndingWith("Util")
+    .orShould().haveSimpleNameEndingWith("Utils")
+    .orShould().haveSimpleNameEndingWith("Helper")
+    .orShould().haveSimpleNameEndingWith("Manager")
+    .orShould().haveSimpleNameEndingWith("DTO");
+```
+
+Scope the analysis to your own packages (`@AnalyzeClasses(packages = "com.alva.bc05")`) so proto- and Quarkus-generated classes don't trip the suffix rules.
+
+## Native-image survival rules
+
+- Any class serialized by Jackson (DTOs, Kafka payloads) that is NOT touched by Quarkus build-time processing: annotate `@RegisterForReflection`.
+- Resources (SQL files, i18n bundles, certs): declare in `quarkus.native.resources.includes` if read at runtime via classpath.
+- Avoid libraries relying on dynamic proxies/bytecode generation at runtime. Prefer Quarkus extensions over raw libraries — extensions do build-time registration for you.
+- Verify with a native integration test: `@QuarkusIntegrationTest` runs the same tests against the built binary. CI must run `./mvnw verify -Dnative` at least on release branches.
+
+## Testing strategy
+
+| Layer | Test type | Tools |
+|---|---|---|
+| domain | plain JUnit 5 unit tests, no Quarkus | JUnit, AssertJ |
+| application | unit tests with mocked ports | Mockito |
+| infrastructure/persistence | `@QuarkusTest` + Dev Services (Testcontainers Postgres) | REST Assured n/a |
+| REST/gRPC adapters | `@QuarkusTest` + REST Assured / gRPC client | |
+| native binary | `@QuarkusIntegrationTest` | |
+
+Keep coverage meaningful: mutation testing (PIT) on domain + application layers is the quality gate, not raw line coverage.

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/quarkus-kafka-messaging/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: quarkus-kafka-messaging
+description: Standard for asynchronous event-driven messaging with Apache Kafka in Quarkus native services — CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, DLQ, and W3C trace context propagation. Use this skill whenever the user mentions Kafka, events, messaging, publish/subscribe, producers, consumers, outbox, domain events between services, SmallRye Reactive Messaging, or asynchronous integration between bounded contexts — even if they just say "emit an event" or "listen to a topic". Includes event, payload, consumer, publisher and channel naming conventions.
+---
+
+# Kafka Messaging Standard (Quarkus + SmallRye Reactive Messaging)
+
+Events are the public contract between services (bounded contexts in DDD projects, but the standard applies to any Quarkus backend). Everything below is the default standard; a project directive (CLAUDE.md, ADR, explicit instruction) may override it — otherwise deviations require a change request.
+
+Extension: `quarkus-messaging-kafka` (SmallRye Reactive Messaging). Native-compatible out of the box; payload classes need `@RegisterForReflection`.
+
+## Topic naming
+
+```
+<org>.<module>.<entity>.<event-type>.v<major>     # <module> = BC code or service name
+alva.bc05.user.registered.v1
+alva.bc01.subscription.status-changed.v2
+```
+
+- Kebab-case segments, past-tense event types.
+- Version bumps ONLY on breaking schema changes; additive fields do not bump.
+- One entity type per topic. Partitioning key = entity id (guarantees per-entity ordering).
+
+## Event envelope: CloudEvents 1.0 (binary mode)
+
+Producers emit CloudEvents in **binary mode** (attributes as Kafka headers `ce_*`, payload = plain JSON body). SmallRye supports this natively:
+
+```properties
+mp.messaging.outgoing.user-registered.connector=smallrye-kafka
+mp.messaging.outgoing.user-registered.topic=alva.bc05.user.registered.v1
+mp.messaging.outgoing.user-registered.cloud-events=true
+mp.messaging.outgoing.user-registered.cloud-events-source=//alva/bc05
+mp.messaging.outgoing.user-registered.cloud-events-type=com.alva.bc05.user.registered.v1
+mp.messaging.outgoing.user-registered.value.serializer=io.quarkus.kafka.client.serialization.ObjectMapperSerializer
+```
+
+Required attributes: `id` (UUID, = outbox event id), `source`, `type`, `time`, `subject` (entity id). Mandatory custom header: `traceparent` (W3C — propagated automatically when OTel is enabled, see observability skill).
+
+Payload schema:
+- JSON, documented as JSON Schema stored in a `contracts/` repo folder per topic version.
+- Payload = event facts, not full entity dumps. Include `entityId`, `occurredAt`, changed fields.
+
+## Producing: transactional outbox (mandatory for domain events)
+
+Never publish directly from a use case in the same breath as a DB write — dual-write problem. Standard:
+
+1. Use case (in the SAME JDBC transaction as the state change) inserts into the outbox table.
+2. A relay publishes to Kafka (Debezium outbox connector preferred; scheduled poller as fallback for environments without Kafka Connect).
+
+Standard outbox table (one per service):
+
+```sql
+CREATE TABLE outbox_event (
+  id            UUID PRIMARY KEY,
+  aggregate_type VARCHAR(64)  NOT NULL,   -- "user"
+  aggregate_id   VARCHAR(64)  NOT NULL,   -- partition key
+  event_type     VARCHAR(128) NOT NULL,   -- "com.alva.bc05.user.registered.v1"
+  payload        JSONB        NOT NULL,
+  traceparent    VARCHAR(64)  NOT NULL,   -- captured at insert time (W3C Trace Context)
+  created_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  published_at   TIMESTAMPTZ  NULL        -- poller mode only
+);
+```
+
+**Payload traceability (mandatory):** besides the `traceparent` column (used by the relay to set the Kafka header), the `payload` jsonb itself must embed a `traceContext` block for audit and immutability:
+
+```json
+{
+  "eventId": "evt-883920-a1",
+  "eventType": "ProductOrderStateChangeEvent",
+  "traceContext": {
+    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
+    "span_id": "00f067aa0ba902b7"
+  },
+  "event": { "productOrder": { "id": "6a43...", "state": "Acknowledged" } }
+}
+```
+
+Both `traceparent` and `traceContext` are captured at insert time from `Span.current().getSpanContext()` — manual construction of trace strings is prohibited (see quarkus-observability-otel skill).
+
+The domain/application layer only knows an outbound port `EventPublisher.publish(DomainEvent e)`; the outbox insert is its JDBC adapter, `OutboxEventPublisher` in `infrastructure/messaging`.
+
+Fire-and-forget technical messages (metrics, notifications with no consistency requirement) MAY use a direct `Emitter`:
+
+```java
+@Inject @Channel("audit-out") Emitter<AuditEventPayload> audit;
+```
+
+### Naming
+
+Canonical rules in the quarkus-hexagonal-core skill; messaging specifics:
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Domain event | past tense, no suffix, in `domain/event` | `UserRegistered` |
+| Wire payload DTO | `<Event>Payload`, in `infrastructure/messaging/dto` | `UserRegisteredPayload` |
+| Outbound port | `EventPublisher` (capability, no technology) | |
+| Publisher adapter | `Outbox<Port>` / `Kafka<Port>` | `OutboxEventPublisher` |
+| Consumer | `<Event>Consumer` | `UserRegisteredConsumer` |
+| Outbox relay job | `<Task>Job` | `OutboxRelayJob` |
+| Event ↔ payload mapper | `<Entity>EventMapper` | `UserEventMapper` |
+| SmallRye channel | `<entity>-<event>-in` / `-out`, kebab-case | `user-registered-in` |
+| CloudEvents `type` | `<javaPackageStyle>.<entity>.<event>.v<major>` | `com.alva.bc05.user.registered.v1` |
+
+Keep the domain event (`UserRegistered`) and the wire payload (`UserRegisteredPayload`) as separate classes even when their fields match: the domain event is free to change with the model, while the payload is a published contract versioned by topic. Never annotate the domain event with Jackson or `@RegisterForReflection` — that annotation belongs on the payload.
+
+## Consuming
+
+```java
+@ApplicationScoped
+public class UserRegisteredConsumer {
+
+    @Incoming("user-registered-in")
+    @Blocking            // JDBC inside → run on worker thread (or virtual thread)
+    public void on(UserRegisteredPayload payload) {   // wire DTO, not the domain event
+        // 1. idempotency check  2. delegate to use case  3. done
+    }
+}
+```
+
+```properties
+mp.messaging.incoming.user-registered-in.connector=smallrye-kafka
+mp.messaging.incoming.user-registered-in.topic=alva.bc05.user.registered.v1
+mp.messaging.incoming.user-registered-in.group.id=${quarkus.application.name}
+mp.messaging.incoming.user-registered-in.auto.offset.reset=earliest
+mp.messaging.incoming.user-registered-in.failure-strategy=delayed-retry-then-dead-letter-queue
+mp.messaging.incoming.user-registered-in.dead-letter-queue.topic=alva.bc05.user.registered.v1.dlq
+```
+
+Rules:
+- **Idempotency is mandatory**: `processed_event(consumer_group, event_id)` table checked/inserted in the same transaction as the side effects. Kafka is at-least-once; duplicates WILL happen.
+- Consumer group = service name; stable across deployments.
+- Failure strategy: bounded retries with delay, then DLQ topic `<topic>.dlq`. DLQ messages keep original headers plus `dead-letter-reason`. A DLQ must have an owner and an alert — never a silent graveyard.
+- Poison-pill safety: deserialization failures also route to DLQ (`...deserialization-failure-handler` or failure strategy), never block the partition.
+- Consumers validate against the payload's JSON Schema version; unknown additive fields are ignored (tolerant reader).
+
+## Ordering & delivery semantics
+
+- Per-entity ordering via partition key = aggregate id. No global ordering assumptions.
+- Exactly-once is NOT assumed; design consumers idempotent instead of enabling Kafka transactions by default.
+
+## Checklist for a new event
+
+1. Define `<Event>Payload` record + JSON Schema in `contracts/`, name the topic and channel per convention.
+2. Producer: outbox insert in use-case transaction; relay config.
+3. `@RegisterForReflection` on the payload record (never on the domain event).
+4. Consumer(s): idempotency table entry, DLQ topic + alert, `@Blocking` if JDBC.
+5. Contract test: serialize/deserialize round-trip against the JSON Schema.