# quarkusio/quarkus-super-heroes architecture

> Architecture diagram of the GitHub repository quarkusio/quarkus-super-heroes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quarkusio/quarkus-super-heroes
- Repository: https://github.com/quarkusio/quarkus-super-heroes

## Overview

#### 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`.

Main entry points: [`rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/service/FightService.java`](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/service/FightService.java) (Fight coordinator), [`ui-super-heroes/src/main/webui/src/app/App.js`](https://github.com/quarkusio/quarkus-super-heroes/blob/main/ui-super-heroes/src/main/webui/src/app/App.js) (React SPA + Quinoa), [`grpc-locations/src/main/kotlin/io/quarkus/sample/superheroes/location/grpc/LocationGrpcService.kt`](https://github.com/quarkusio/quarkus-super-heroes/blob/main/grpc-locations/src/main/kotlin/io/quarkus/sample/superheroes/location/grpc/LocationGrpcService.kt) (Locations gRPC service), [`rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/rest/FightResource.java`](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/rest/FightResource.java) (Fight REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_browser(("Browser user<br/>client"))
  node_ui["React SPA + Quinoa<br/>Quarkus UI service<br/>[App.js]"]
  node_fight_api_client["Fight API client<br/>frontend API layer<br/>[fight-service.js]"]
  node_ui_environment["UI environment endpoint<br/>REST resource<br/>[EnvResource.java]"]
end

subgraph group_fight["Fight orchestration"]
  node_fight_resource["Fight REST API<br/>reactive REST resource<br/>[FightResource.java]"]
  node_fight_service["Fight coordinator<br/>application service<br/>[FightService.java]"]
  node_fight_mongo[("Fight history<br/>MongoDB")]
  node_fight_avro["Fight event contract<br/>Avro schema<br/>[fight.avsc]"]
end

subgraph group_catalogs["Catalog services"]
  node_heroes_api["Heroes service<br/>HTTP CRUD service<br/>[HeroResource.java]"]
  node_hero_repository["Hero repository<br/>Hibernate Reactive Panache"]
  node_villains_api["Villains service<br/>HTTP CRUD service"]
  node_catalog_database[("Catalog database<br/>relational database")]
end

subgraph group_dependencies["Remote dependencies"]
  node_locations_grpc["Locations gRPC service<br/>Kotlin gRPC service"]
  node_location_proto["Location contract<br/>protobuf schema"]
  node_location_database[("Location database<br/>relational database")]
  node_narration["Narration service<br/>REST + AI service"]
  node_openai["OpenAI<br/>external AI provider"]
end

subgraph group_events["Event statistics"]
  node_kafka["Kafka<br/>event broker"]
  node_statistics_listener["Statistics processor<br/>Kafka listener<br/>[SuperStats.java]"]
  node_statistics_avro["Statistics event contract<br/>Avro schema<br/>[fight.avsc]"]
  node_stats_websocket["Statistics WebSocket<br/>WebSocket endpoint"]
end

subgraph group_platform["Runtime platform"]
  node_deployment["Containers and deployments<br/>Compose, Helm, manifests<br/>[java25.yml]"]
  node_observability["Grafana LGTM<br/>OTLP observability stack<br/>[monitoring.yml]"]
end

node_browser -->|"uses"| node_ui
node_ui -->|"calls through"| node_fight_api_client
node_ui -->|"reads environment"| node_ui_environment
node_fight_api_client -->|"REST"| node_fight_resource
node_fight_resource -->|"delegates"| node_fight_service
node_fight_service -->|"REST client"| node_heroes_api
node_fight_service -->|"REST client"| node_villains_api
node_fight_service -->|"gRPC client"| node_locations_grpc
node_fight_service -->|"REST client"| node_narration
node_fight_service -->|"persists fights"| node_fight_mongo
node_fight_service -->|"serializes"| node_fight_avro
node_fight_service -->|"publishes fight events"| node_kafka
node_heroes_api -->|"uses"| node_hero_repository
node_hero_repository -->|"persists"| node_catalog_database
node_villains_api -->|"persists"| node_catalog_database
node_locations_grpc -->|"implements"| node_location_proto
node_locations_grpc -->|"persists"| node_location_database
node_narration -->|"LangChain4J"| node_openai
node_kafka -->|"consumes events"| node_statistics_listener
node_statistics_avro -->|"deserializes"| node_statistics_listener
node_statistics_listener -->|"pushes updates"| node_stats_websocket
node_browser -->|"receives live stats"| node_stats_websocket
node_deployment -.->|"deploys"| node_fight_resource
node_observability -.->|"receives OTLP"| node_fight_service

click node_ui "https://github.com/quarkusio/quarkus-super-heroes/blob/main/ui-super-heroes/src/main/webui/src/app/App.js"
click node_fight_api_client "https://github.com/quarkusio/quarkus-super-heroes/blob/main/ui-super-heroes/src/main/webui/src/app/shared/api/fight-service.js"
click node_ui_environment "https://github.com/quarkusio/quarkus-super-heroes/blob/main/ui-super-heroes/src/main/java/io/quarkus/sample/superheroes/ui/EnvResource.java"
click node_fight_resource "https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/rest/FightResource.java"
click node_fight_service "https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/service/FightService.java"
click node_fight_avro "https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/avro/fight.avsc"
click node_heroes_api "https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/rest/HeroResource.java"
click node_hero_repository "https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/repository/HeroRepository.java"
click node_villains_api "https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-villains/src/main/java/io/quarkus/sample/superheroes/villain/rest/VillainResource.java"
click node_locations_grpc "https://github.com/quarkusio/quarkus-super-heroes/blob/main/grpc-locations/src/main/kotlin/io/quarkus/sample/superheroes/location/grpc/LocationGrpcService.kt"
click node_location_proto "https://github.com/quarkusio/quarkus-super-heroes/blob/main/grpc-locations/src/main/proto/locationservice-v1.proto"
click node_narration "https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-narration/src/main/java/io/quarkus/sample/superheroes/narration/service/NarrationService.java"
click node_statistics_listener "https://github.com/quarkusio/quarkus-super-heroes/blob/main/event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/listener/SuperStats.java"
click node_statistics_avro "https://github.com/quarkusio/quarkus-super-heroes/blob/main/event-statistics/src/main/avro/fight.avsc"
click node_stats_websocket "https://github.com/quarkusio/quarkus-super-heroes/blob/main/event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/endpoint/EventStatsWebSocket.java"
click node_deployment "https://github.com/quarkusio/quarkus-super-heroes/blob/main/deploy/docker-compose/java25.yml"
click node_observability "https://github.com/quarkusio/quarkus-super-heroes/blob/main/monitoring/docker-compose/monitoring.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_ui,node_fight_api_client,node_ui_environment toneBlue
class node_fight_resource,node_fight_service,node_fight_mongo,node_fight_avro toneAmber
class node_heroes_api,node_hero_repository,node_villains_api,node_catalog_database toneMint
class node_locations_grpc,node_location_proto,node_location_database,node_narration,node_openai toneRose
class node_kafka,node_statistics_listener,node_statistics_avro,node_stats_websocket toneIndigo
class node_deployment,node_observability toneTeal
```

## Components

### User interface

- **Browser user**: client
- [React SPA + Quinoa](https://github.com/quarkusio/quarkus-super-heroes/blob/main/ui-super-heroes/src/main/webui/src/app/App.js): Quarkus UI service · Chooses fighters, starts battles, and shows history. · `ui-super-heroes/src/main/webui/src/app/App.js`
- [Fight API client](https://github.com/quarkusio/quarkus-super-heroes/blob/main/ui-super-heroes/src/main/webui/src/app/shared/api/fight-service.js): frontend API layer · `ui-super-heroes/src/main/webui/src/app/shared/api/fight-service.js`
- [UI environment endpoint](https://github.com/quarkusio/quarkus-super-heroes/blob/main/ui-super-heroes/src/main/java/io/quarkus/sample/superheroes/ui/EnvResource.java): REST resource · `ui-super-heroes/src/main/java/io/quarkus/sample/superheroes/ui/EnvResource.java`

### Fight orchestration

- [Fight REST API](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/rest/FightResource.java): reactive REST resource · `rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/rest/FightResource.java`
- [Fight coordinator](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/service/FightService.java): application service · Coordinates dependencies, persistence, resilience, and event publication. · `rest-fights/src/main/java/io/quarkus/sample/superheroes/fight/service/FightService.java`
- **Fight history**: MongoDB
- [Fight event contract](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-fights/src/main/avro/fight.avsc): Avro schema · `rest-fights/src/main/avro/fight.avsc`

### Catalog services

- [Heroes service](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/rest/HeroResource.java): HTTP CRUD service · `rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/rest/HeroResource.java`
- [Hero repository](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/repository/HeroRepository.java): Hibernate Reactive Panache · `rest-heroes/src/main/java/io/quarkus/sample/superheroes/hero/repository/HeroRepository.java`
- [Villains service](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-villains/src/main/java/io/quarkus/sample/superheroes/villain/rest/VillainResource.java): HTTP CRUD service · Uses Hibernate ORM active record persistence. · `rest-villains/src/main/java/io/quarkus/sample/superheroes/villain/rest/VillainResource.java`
- **Catalog database**: relational database

### Remote dependencies

- [Locations gRPC service](https://github.com/quarkusio/quarkus-super-heroes/blob/main/grpc-locations/src/main/kotlin/io/quarkus/sample/superheroes/location/grpc/LocationGrpcService.kt): Kotlin gRPC service · `grpc-locations/src/main/kotlin/io/quarkus/sample/superheroes/location/grpc/LocationGrpcService.kt`
- [Location contract](https://github.com/quarkusio/quarkus-super-heroes/blob/main/grpc-locations/src/main/proto/locationservice-v1.proto): protobuf schema · `grpc-locations/src/main/proto/locationservice-v1.proto`
- **Location database**: relational database
- [Narration service](https://github.com/quarkusio/quarkus-super-heroes/blob/main/rest-narration/src/main/java/io/quarkus/sample/superheroes/narration/service/NarrationService.java): REST + AI service · Produces text and optional imagery for completed fights. · `rest-narration/src/main/java/io/quarkus/sample/superheroes/narration/service/NarrationService.java`
- **OpenAI**: external AI provider

### Event statistics

- **Kafka**: event broker
- [Statistics processor](https://github.com/quarkusio/quarkus-super-heroes/blob/main/event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/listener/SuperStats.java): Kafka listener · Derives rankings and aggregate hero, villain, and team statistics. · `event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/listener/SuperStats.java`
- [Statistics event contract](https://github.com/quarkusio/quarkus-super-heroes/blob/main/event-statistics/src/main/avro/fight.avsc): Avro schema · Local consumer copy of the fight event contract. · `event-statistics/src/main/avro/fight.avsc`
- [Statistics WebSocket](https://github.com/quarkusio/quarkus-super-heroes/blob/main/event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/endpoint/EventStatsWebSocket.java): WebSocket endpoint · `event-statistics/src/main/java/io/quarkus/sample/superheroes/statistics/endpoint/EventStatsWebSocket.java`

### Runtime platform

- [Containers and deployments](https://github.com/quarkusio/quarkus-super-heroes/blob/main/deploy/docker-compose/java25.yml): Compose, Helm, manifests · Supports JVM/native containers and Kubernetes-family targets. · `deploy/docker-compose/java25.yml`
- [Grafana LGTM](https://github.com/quarkusio/quarkus-super-heroes/blob/main/monitoring/docker-compose/monitoring.yml): OTLP observability stack · Receives traces, metrics, and logs. · `monitoring/docker-compose/monitoring.yml`

## Connections

- Browser user → React SPA + Quinoa: uses
- React SPA + Quinoa → Fight API client: calls through
- React SPA + Quinoa → UI environment endpoint: reads environment
- Fight API client → Fight REST API: REST
- Fight REST API → Fight coordinator: delegates
- Fight coordinator → Heroes service: REST client
- Fight coordinator → Villains service: REST client
- Fight coordinator → Locations gRPC service: gRPC client
- Fight coordinator → Narration service: REST client
- Fight coordinator → Fight history: persists fights
- Fight coordinator → Fight event contract: serializes
- Fight coordinator → Kafka: publishes fight events
- Heroes service → Hero repository: uses
- Hero repository → Catalog database: persists
- Villains service → Catalog database: persists
- Locations gRPC service → Location contract: implements
- Locations gRPC service → Location database: persists
- Narration service → OpenAI: LangChain4J
- Kafka → Statistics processor: consumes events
- Statistics event contract → Statistics processor: deserializes
- Statistics processor → Statistics WebSocket: pushes updates
- Browser user → Statistics WebSocket: receives live stats
- Containers and deployments → Fight REST API: deploys
- Grafana LGTM → Fight coordinator: receives OTLP