quarkusio/quarkus-super-heroes

# 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

```bash
# 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:**

| Service | Port | Type | Database | Language |
|---------|------|------|----------|----------|
| rest-fights | 8082 | REST (reactive) | MongoDB | Java |
| rest-heroes | 8083 | REST (reactive) | PostgreSQL | Java |
| rest-villains | 8084 | REST (blocking) | PostgreSQL | Java |
| rest-narration | 8087 | REST (blocking) | — (OpenAI) | Java |
| event-statistics | 8085 | Kafka consumer + WebSocket | — | Java |
| grpc-locations | 8089 | gRPC (blocking) | MariaDB | Kotlin |
| ui-super-heroes | 8080 | React (via Quinoa) | — | TypeScript |

**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 → Jaeger (tracing), Prometheus (metrics)

## Key Technical Details

- **Java 21** required (`maven.compiler.release=21`)
- **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 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

## Deployment Resources

Generated deployment descriptors live in `deploy/`:
- `deploy/docker-compose/` — Docker Compose files (e.g., `java21.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-resources.sh`. Do not edit them manually.

## CI/CD

- **Required check**: `simple-build-test.yml` — runs on all PRs (JVM + container + native builds)
- **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