CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Quarkus Super Heroes is a microservices-based application showcasing Quarkus features. It consists of 7 services communicating via REST, gRPC, and Kafka, with a React UI.

Build Commands

# Build and test everything (JVM)
./mvnw clean verify

# Build a single module
cd rest-heroes && ./mvnw clean verify

# Build without tests
./mvnw clean package -DskipTests

# Build with container images
./mvnw clean package -Dquarkus.container-image.build=true -DskipTests

# Native build (requires GraalVM/Mandrel)
./mvnw clean verify -Pnative

# Run a single test class
cd rest-heroes && ./mvnw test -Dtest=HeroResourceTest

# Run a single test method
cd rest-heroes && ./mvnw test -Dtest=HeroResourceTest#testGetAllHeroes

# Run integration tests only
cd rest-heroes && ./mvnw verify -DskipUnitTests

# Run in dev mode (starts dependencies via Dev Services)
cd rest-heroes && ./mvnw quarkus:dev

Architecture

Services and their ports:

Communication flow:

• UI → rest-fights (REST)
• rest-fights → rest-heroes, rest-villains, rest-narration (REST via SmallRye Stork)
• rest-fights → grpc-locations (gRPC)
• rest-fights → Kafka (Avro messages via Apicurio Registry)
• event-statistics ← Kafka consumer

Observability: OpenTelemetry → Grafana LGTM stack (Grafana, Loki, Tempo, Prometheus) via OTLP

Key Technical Details

• Java 25 required (maven.compiler.release=25)
• Quarkus platform version managed via quarkus.platform.version property in root pom.xml
• Maven wrapper (./mvnw) — do not use system Maven
• Reactive vs blocking: rest-heroes and rest-fights use Hibernate Reactive with Panache; rest-villains uses Hibernate ORM with Panache (blocking)
• Contract-first: All REST services (rest-villains, rest-heroes, rest-narration, rest-fights) use the Quarkiverse OpenAPI Generator Server extension to generate JAX-RS resource interfaces from src/main/resources/openapi/openapi.yml at build time
• Contract testing: Pact consumer/provider tests across services (pact files in src/test/resources/pacts/)
• Dev Services: Quarkus auto-starts databases, Kafka, etc. in dev/test mode — Docker/Podman must be running
• Test messaging: Kafka replaced with smallrye-in-memory connector in %test profile

Code Style

• EditorConfig enforces formatting — 2-space indent (default), 180-char line length, LF endings
• Java imports order: $*, java.**, javax.**, jakarta.**, org.**, org.apache.commons.**, org.springframework.**, io.quarkus.**, io.quarkus.sample.**, *
• Injection style varies by module: rest-villains uses field injection (@Inject); rest-heroes, rest-narration, grpc-locations use constructor injection

Documentation Site

• Published at: https://quarkus.io/quarkus-super-heroes
• Source: docs/ module — a Quarkus Roq static site (not a traditional application module)
• Theme: quarkus-roq-theme-default (Tailwind CSS, sidebar navigation, dark mode)
• Build: cd docs && mvn quarkus:dev for local dev, or QUARKUS_ROQ_GENERATOR_BATCH=true mvn -B package quarkus:run -DskipTests for static generation
• Deployment: .github/workflows/deploy-docs-site.yml — publishes to GitHub Pages after CI passes
• Content: docs/content/ — FrontMatter markdown pages curated from the original READMEs
• Images: docs/public/images/ — copies of images from service directories
• Navigation: docs/data/menu.yml
• README pattern: Service READMEs are intentionally brief (intro + dev mode command + link to docs site). All detailed documentation lives in the docs site to avoid duplication.

Deployment Resources

Generated deployment descriptors live in deploy/:

• deploy/docker-compose/ — Docker Compose files (e.g., java25.yml, native.yml, monitoring.yml)
• deploy/k8s/ — Kubernetes/OpenShift/Minikube/Knative descriptors

These are auto-generated by scripts/generate-docker-compose-resources.sh and scripts/generate-k8s-helm-resources.sh. Do not edit them manually.

CI/CD

• Required check: simple-build-test.yml — runs on all PRs (JVM + container + native builds)
• Docs deployment: deploy-docs-site.yml — publishes docs site to GitHub Pages after CI passes on main, or on docs-only changes
• Container images: pushed to quay.io/quarkus-super-heroes for amd64 and arm64
• Composite actions: .github/actions/save-container-image/ and .github/actions/load-container-image/ for passing container images between workflow jobs
• GitHub Actions allowlist: the quarkusio org restricts allowed actions — see https://github.com/quarkusio/quarkus/wiki/GitHubActions