quarkusio/quarkus-super-heroes

Purpose and Topology

This repository is a Quarkus microservices sample for superhero battles, demonstrating synchronous REST/gRPC calls, Kafka eventing, persistence, resilience, OpenTelemetry, and multiple deployment targets. It is a collection of independently built and run Maven projects, not a single multi-module build. Root orientation and system documentation: README.md, pom.xml, images/plantuml/application-architecture.puml.

User Entry Point

The user-facing application is a React SPA packaged and served by Quarkus Quinoa. Its frontend calls the fight API to choose fighters, initiate battles, and show fight history. Key boundaries: ui-super-heroes/src/main/webui/src/app/App.js, ui-super-heroes/src/main/webui/src/app/shared/api/fight-service.js, ui-super-heroes/src/main/java/io/quarkus/sample/superheroes/ui/EnvResource.java.

Fight Orchestrator

rest-fights is the central reactive REST service and primary backend entry point. FightResource accepts fight requests; FightService coordinates downstream hero, villain, location, and narration services, maps their DTOs into fight domain records, persists fights in MongoDB, and publishes Avro fight events to Kafka. It also owns health checks, configuration, OpenAPI contract, and fault-tolerance boundary for dependency failures. Paths: rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/rest/FightResource.java, rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/service/FightService.java, rest-fights/src/main/avro/fight.avsc.

Character Catalog Services

Heroes and villains are independent HTTP CRUD services backed by relational persistence through Panache, exposing resource/service/data-access layers. Heroes use Hibernate Reactive repository style; villains use Hibernate ORM active record style. The fight orchestrator reaches them through REST clients rather than sharing persistence models. Paths: rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/rest/HeroResource.java, rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/repository/HeroRepository.java, rest-villains/src/main/java/io/quarkus/sample/superheroes/villain/rest/VillainResource.java.

Location and Narration Dependencies

Location is a Kotlin gRPC service with a protobuf contract and relational repository; rest-fights consumes it through LocationClient. Narration is a REST service that converts completed fight data into text and optional imagery, delegating AI work to OpenAI through LangChain4J. These are distinct protocol and external-provider boundaries. Paths: grpc-locations/src/main/proto/locationservice-v1.proto, grpc-locations/src/main/kotlin/io/quarkus/sample/superheroes/location/grpc/LocationGrpcService.kt, rest-narration/src/main/java/io/quarkus/sample/superheroes/narration/service/NarrationService.java.

Event Statistics Pipeline

After orchestration, fight events flow asynchronously from Kafka into event-statistics. Listener components derive rankings, aggregate hero/villain/team statistics, and push updates over WebSockets to dashboard/browser clients. The Avro event schema is duplicated locally as the consumer contract. Paths: event-statistics/src/main/avro/fight.avsc, event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/listener/SuperStats.java, event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/endpoint/EventStatsWebSocket.java.

Runtime, Infrastructure, and Delivery

Services target Java 25 on Quarkus, with JVM and native container variants. Local Compose definitions provision service dependencies; deployments support Kubernetes, OpenShift, Minikube, and Knative via Helm or generated manifests. Relational databases serve catalogs/locations, MongoDB stores fights, Kafka transports events, OpenAI supplies narration, and Grafana LGTM receives OTLP traces, metrics, and logs. Paths: deploy/docker-compose/java25.yml, monitoring/docker-compose/monitoring.yml, rest-fights/deploy/helm/kubernetes/Chart.yaml.