---
description: Quarkus conventions
globs: ["src/main/java/**/*.java","src/main/resources/application.properties"]
alwaysApply: false
---

# Quarkus 3

- Run with `./mvnw quarkus:dev` (live reload, Dev Services start databases/brokers in containers). Test with `./mvnw verify`.
- REST endpoints with Quarkus REST (`@Path`, `@GET`, `@POST`) returning DTO `record`s; validate with Hibernate Validator (`@Valid`, constraint annotations). Map errors with `@ServerExceptionMapper`.
- Beans are CDI: `@ApplicationScoped` services with constructor injection. Avoid `@Singleton` unless you need eager, unproxied beans.
- Persistence with Hibernate ORM Panache: entities or repositories (`PanacheRepository<Order>`), queries like `find("status", Status.OPEN).page(0, 50)`. Writes inside `@Transactional` service methods.
- Schema via Flyway migrations (`src/main/resources/db/migration`), not `drop-and-create` outside dev.
- Config with `@ConfigMapping(prefix = "app")` interfaces; secrets from env or a vault, profiles via `%dev.`/`%prod.` prefixes.
- Use Quarkus extensions (`quarkus ext add rest-client-jackson`) instead of raw libraries when one exists.
- Keep code native-image friendly: avoid runtime reflection and dynamic class loading; register with `@RegisterForReflection` when needed.
- Blocking vs reactive: be consistent per endpoint; annotate `@Blocking`/`@NonBlocking` when mixing, and never block the event loop.
- Health and metrics via `smallrye-health` and Micrometer.

## Done when
`./mvnw verify` passes with `@QuarkusTest` tests (REST Assured for endpoints).