notifications-gw: Instructions file for Codex

AGENTS.md

Cross-Cutting Conventions

• Java 25, Quarkus 3.x, Maven wrapper only. Always use ./mvnw, never system mvn. The project is a single-module Maven build with no submodules.
• Package root: com.redhat.cloud.notifications. Sub-packages are auth (identity/authentication) and model (DTOs shared with notifications-backend). New REST model POJOs go in the root package.
• No wildcard imports. .editorconfig sets ij_java_names_count_to_use_import_on_demand = 999 to force explicit imports.
• snake_case JSON, camelCase Java. Use @JsonProperty("snake_case_name") on fields whose wire name differs from the Java name. The canonical examples are event_type, org_id, account_id.
• Config prefix: All application-specific properties use notifications.*. Quarkus-managed properties keep their standard prefixes. Every @ConfigProperty must have a defaultValue.
• Logging: Use io.quarkus.logging.Log static methods (Log.infof, Log.errorf, etc.) with %s format placeholders. Never use SLF4J or java.util.logging in application code.
• Metrics prefix: notifications.gw.* for all Micrometer counters. Register counters via MeterRegistry constructor injection. Avoid high-cardinality tags (no org IDs or UUIDs as tag values).
• CDI scope: @ApplicationScoped everywhere. This repo does not use @RequestScoped. REST client interfaces require both @ApplicationScoped and @RegisterRestClient.
• Fault tolerance: @Retry(maxRetries = 5) on every REST client method. No @Timeout, @CircuitBreaker, or @Fallback in this codebase.
• Response envelope: All POST /notifications/ responses use {"result":"success"} on success or {"result":"error","details":"..."} on failure, built via the private buildResponseEntity() helper in GwResource. Do not invent alternative shapes.

Architecture Context

This is a gateway microservice — it receives notification payloads via REST, validates them against notifications-backend, and forwards them to Kafka (platform.notifications.ingress). There is exactly one Kafka producer channel (egress) and no consumers. The gateway does not own any database or persistent state.