# bryanxtong/learnmicroserviceswithspringboot-kafka architecture

> Architecture diagram of the GitHub repository bryanxtong/learnmicroserviceswithspringboot-kafka, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bryanxtong/learnmicroserviceswithspringboot-kafka
- Repository: https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka

## Overview

1. **Repository shape**
   This is a polyrepo-style monorepo for a small Spring microservices system plus a React front end. The main runtime pieces are four Spring Boot services — `multiplication`, `gamification`, `gateway`, and `logs` — plus a browser UI in `challenges-frontend`. Docker assets and a Consul bootstrap/importer live under `docker/`.

2. **User-facing entry point**
   The browser app in `challenges-frontend` is the only direct UI. Its React components are centered around three screens/widgets: challenge solving, last attempts, and leaderboard. The UI talks to the backend through two service clients: `ChallengeApiClient` and `GameApiClient`, so it does not call the domain services directly.

3. **API edge / routing layer**
   `gateway` is the front door for backend traffic. It is a Spring Cloud Gateway application, and the README indicates it is meant to route requests to the backend services with load balancing and service discovery. This is the main network boundary between the UI and the internal service topology.

4. **Multiplication service: challenge generation and validation**
   `multiplication` owns the game-play workflow. It generates multiplication challenges, accepts submitted answers, stores challenge attempts, and manages users. The key components are `ChallengeController`, `ChallengeAttemptController`, `ChallengeGeneratorServiceImpl`, `ChallengeServiceImpl`, `UserController`, and the corresponding repositories.

5. **Multiplication data model**
   The domain is centered on `Challenge`, `ChallengeAttempt`, `ChallengeAttemptDTO`, and `User`. `ChallengeAttemptRepository` and `UserRepository` show that this service owns its own persistence boundary for player and attempt data. It also contains `ChallengeEventPub`, which is the publication boundary for solved-challenge events.

6. **Event contract between services**
   Solved-challenge events are the main asynchronous integration point. The shared event type `ChallengeSolvedEvent` appears in both `multiplication` and `gamification`, under the common `microservices.book.event.challenge` package structure. This is the event payload that decouples gameplay from rewards/leaderboard processing.

7. **Gamification service: badges and leaderboard**
   `gamification` consumes challenge-solved events and turns them into rewards. Its core classes are `GameEventHandler`, `GameServiceImpl`, `LeaderBoardServiceImpl`, and `LeaderBoardController`. It also contains badge processors for different rules: first win, bronze, silver, gold, and lucky number.

8. **Gamification data boundary**
   Gamification persists its own score and badge state via `ScoreRepository` and `BadgeRepository`. Its domain objects are `ScoreCard`, `BadgeCard`, `BadgeType`, and `LeaderBoardRow`. This service is therefore responsible for derived game state, not the raw challenge attempts.

9. **Kafka-backed eventing and log pipeline**
   Kafka is used in two different ways. First, the business event flow likely moves challenge-solved events from `multiplication` to `gamification`. Second, all services use a customized logback Kafka appender (`KafkaAppender`, `KafkaAppenderWithHeader`, `KafkaAggregateLogsKeyingStrategy`) to ship application logs into the `logs` service. The `logs` app is a separate consumer that aggregates these messages.

10. **Observability and tracing**
   The system is designed for centralized logs and distributed tracing. The README mentions Micrometer/Zipkin support, and each service has `logback-spring.xml` plus service-specific configuration files. Observability is therefore a first-class cross-cutting concern, not an afterthought.

11. **Configuration and service discovery**
   The presence of `bootstrap.properties` / `bootstrap.yml`, plus the Consul importer under `docker/consul`, indicates Spring Cloud Consul is used for externalized configuration and service registration/discovery. This is what enables the scale-out example in the README, where multiple instances of `multiplication` and `gamification` can run behind the gateway.

12. **Deployment model**
   Each runnable unit has its own Dockerfile and Maven build. The system is intended to be assembled with `docker-compose`, with a separate container for the Consul bootstrap/importer. The architecture is therefore containerized, service-oriented, and designed to be deployed as independent images rather than a single monolith.

13. **Where the important boundaries are**
   The main boundaries to draw in an architecture diagram are: browser UI vs. gateway, gateway vs. internal services, synchronous gameplay APIs vs. asynchronous Kafka events, and each service’s own persistence boundary. A second cross-cutting boundary is the observability pipeline, where logs flow out of every service into the `logs` consumer.

14. **Code organization clue**
   Tests are organized per service and per subsystem, which reinforces the architecture: each microservice has its own test suite, and `gamification` and `multiplication` have dedicated tests for controllers, services, and badge processors. That mirrors the runtime separation and helps confirm the intended service responsibilities.

Main entry points: [`gateway/src/main/java/microservices/book/gateway/GatewayApplication.java`](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gateway/src/main/java/microservices/book/gateway/GatewayApplication.java) (Gateway), [`multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeServiceImpl.java`](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeServiceImpl.java) (Challenge service), [`gamification/src/main/java/microservices/book/gamification/game/GameEventHandler.java`](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/GameEventHandler.java) (Game handler), [`multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeController.java`](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeController.java) (Challenge APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Frontend"]
  node_node_frontend_app["Challenge UI<br/>React app<br/>[App.js]"]
  node_node_frontend_challenge_component["Challenge screen<br/>React component"]
  node_node_frontend_attempts_component["Last attempts<br/>React component"]
  node_node_frontend_leaderboard_component["Leaderboard<br/>React component"]
  node_node_frontend_challenge_api["Challenge API client"]
  node_node_frontend_game_api["Game API client<br/>[GameApiClient.js]"]
end

subgraph group_group_edge["Edge"]
  node_node_gateway["Gateway"]
end

subgraph group_group_services["Core services"]
  node_node_multiplication_controller["Challenge APIs<br/>web controllers"]
  node_node_multiplication_generator["Challenge generator"]
  node_node_multiplication_service["Challenge service"]
  node_node_multiplication_user["User API<br/>web controller"]
  node_node_multiplication_domain[("Challenge data<br/>domain + repo<br/>[Challenge.java]")]
  node_node_event_contract["Challenge solved event<br/>shared event"]
  node_node_gamification_event["Game handler<br/>event consumer"]
  node_node_gamification_service["Game service"]
  node_node_gamification_leaderboard["Leaderboard service"]
  node_node_gamification_badges["Badge rules<br/>processors"]
  node_node_gamification_data[("Game data<br/>domain + repo")]
end

subgraph group_group_platform["Platform"]
  node_node_logs["Logs service<br/>Kafka consumer<br/>[LogsConsumer.java]"]
  node_node_kafka_logging["Kafka logging<br/>logback appender"]
  node_node_consul["Consul bootstrap<br/>infra config"]
end

node_node_frontend_app -->|"renders"| node_node_frontend_challenge_component
node_node_frontend_app -->|"renders"| node_node_frontend_attempts_component
node_node_frontend_app -->|"renders"| node_node_frontend_leaderboard_component
node_node_frontend_challenge_component -->|"calls"| node_node_frontend_challenge_api
node_node_frontend_leaderboard_component -->|"calls"| node_node_frontend_game_api
node_node_frontend_attempts_component -->|"calls"| node_node_frontend_challenge_api
node_node_frontend_challenge_api -->|"routes via"| node_node_gateway
node_node_frontend_game_api -->|"routes via"| node_node_gateway
node_node_gateway -->|"routes to"| node_node_multiplication_controller
node_node_gateway -->|"routes to"| node_node_gamification_leaderboard
node_node_multiplication_controller -->|"delegates"| node_node_multiplication_service
node_node_multiplication_service -->|"uses"| node_node_multiplication_generator
node_node_multiplication_service -->|"stores"| node_node_multiplication_domain
node_node_multiplication_service -->|"publishes"| node_node_event_contract
node_node_gamification_event -->|"consumes"| node_node_event_contract
node_node_gamification_event -->|"delegates"| node_node_gamification_service
node_node_gamification_service -->|"applies"| node_node_gamification_badges
node_node_gamification_service -->|"updates"| node_node_gamification_data
node_node_gamification_leaderboard -->|"reads"| node_node_gamification_data
node_node_logs -->|"receives from"| node_node_kafka_logging
node_node_multiplication_controller -.->|"emits logs"| node_node_kafka_logging
node_node_gamification_event -.->|"emits logs"| node_node_kafka_logging
node_node_gateway -.->|"emits logs"| node_node_kafka_logging
node_node_consul -.->|"registers/configures"| node_node_gateway
node_node_consul -.->|"registers/configures"| node_node_multiplication_controller
node_node_consul -.->|"registers/configures"| node_node_gamification_event

click node_node_frontend_app "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/App.js"
click node_node_frontend_challenge_component "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/components/ChallengeComponent.js"
click node_node_frontend_attempts_component "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/components/LastAttemptsComponent.js"
click node_node_frontend_leaderboard_component "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/components/LeaderBoardComponent.js"
click node_node_frontend_challenge_api "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/services/ChallengeApiClient.js"
click node_node_frontend_game_api "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/services/GameApiClient.js"
click node_node_gateway "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gateway/src/main/java/microservices/book/gateway/GatewayApplication.java"
click node_node_multiplication_controller "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeController.java"
click node_node_multiplication_generator "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeGeneratorServiceImpl.java"
click node_node_multiplication_service "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeServiceImpl.java"
click node_node_multiplication_user "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/user/UserController.java"
click node_node_multiplication_domain "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/Challenge.java"
click node_node_event_contract "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/event/challenge/ChallengeSolvedEvent.java"
click node_node_gamification_event "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/GameEventHandler.java"
click node_node_gamification_service "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/GameServiceImpl.java"
click node_node_gamification_leaderboard "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/LeaderBoardServiceImpl.java"
click node_node_gamification_badges "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/badgeprocessors/BadgeProcessor.java"
click node_node_gamification_data "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/ScoreRepository.java"
click node_node_logs "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/logs/src/main/java/microservices/book/logs/LogsConsumer.java"
click node_node_kafka_logging "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gateway/src/main/java/logback/kafka/KafkaAppenderWithHeader.java"
click node_node_consul "https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/docker/consul/consul-kv-docker.json"

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_node_frontend_app,node_node_frontend_challenge_component,node_node_frontend_attempts_component,node_node_frontend_leaderboard_component,node_node_frontend_challenge_api,node_node_frontend_game_api toneBlue
class node_node_gateway toneAmber
class node_node_multiplication_controller,node_node_multiplication_generator,node_node_multiplication_service,node_node_multiplication_user,node_node_multiplication_domain,node_node_event_contract,node_node_gamification_event,node_node_gamification_service,node_node_gamification_leaderboard,node_node_gamification_badges,node_node_gamification_data toneMint
class node_node_logs,node_node_kafka_logging,node_node_consul toneRose
```

## Components

### Frontend

Browser UI and API clients

- [Challenge UI](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/App.js): React app · Browser entry point for solving challenges, viewing attempts, and leaderboard · `challenges-frontend/src/App.js`
- [Challenge screen](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/components/ChallengeComponent.js): React component · Challenge solving widget · `challenges-frontend/src/components/ChallengeComponent.js`
- [Last attempts](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/components/LastAttemptsComponent.js): React component · Recent attempt history widget · `challenges-frontend/src/components/LastAttemptsComponent.js`
- [Leaderboard](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/components/LeaderBoardComponent.js): React component · Leaderboard widget · `challenges-frontend/src/components/LeaderBoardComponent.js`
- [Challenge API client](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/services/ChallengeApiClient.js): client · Frontend client for gameplay and attempt endpoints · `challenges-frontend/src/services/ChallengeApiClient.js`
- [Game API client](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/challenges-frontend/src/services/GameApiClient.js): client · Frontend client for leaderboard and reward data · `challenges-frontend/src/services/GameApiClient.js`

### Edge

API routing boundary

- [Gateway](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gateway/src/main/java/microservices/book/gateway/GatewayApplication.java): Spring Cloud Gateway · Front door routing requests to backend services · `gateway/src/main/java/microservices/book/gateway/GatewayApplication.java`

### Core services

Business services and shared event contract

- [Challenge APIs](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeController.java): web controllers · Challenge and attempt HTTP entry points · `multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeController.java`
- [Challenge generator](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeGeneratorServiceImpl.java): service · Builds multiplication challenges and validates attempts · `multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeGeneratorServiceImpl.java`
- [Challenge service](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeServiceImpl.java): service · Coordinates gameplay and attempt handling · `multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeServiceImpl.java`
- [User API](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/user/UserController.java): web controller · User management endpoint · `multiplication/src/main/java/microservices/book/multiplication/user/UserController.java`
- [Challenge data](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/multiplication/challenge/Challenge.java): domain + repo · Challenge, attempt, user, and persistence boundary · `multiplication/src/main/java/microservices/book/multiplication/challenge/Challenge.java`
- [Challenge solved event](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/multiplication/src/main/java/microservices/book/event/challenge/ChallengeSolvedEvent.java): shared event · Common event payload used between gameplay and gamification · `multiplication/src/main/java/microservices/book/event/challenge/ChallengeSolvedEvent.java`
- [Game handler](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/GameEventHandler.java): event consumer · Consumes solved-challenge events · `gamification/src/main/java/microservices/book/gamification/game/GameEventHandler.java`
- [Game service](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/GameServiceImpl.java): service · Awards badges and updates derived game state · `gamification/src/main/java/microservices/book/gamification/game/GameServiceImpl.java`
- [Leaderboard service](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/LeaderBoardServiceImpl.java): service · Serves leaderboard views and ranking data · `gamification/src/main/java/microservices/book/gamification/game/LeaderBoardServiceImpl.java`
- [Badge rules](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/badgeprocessors/BadgeProcessor.java): processors · First win, bronze, silver, gold, and lucky-number badge processors · `gamification/src/main/java/microservices/book/gamification/game/badgeprocessors/BadgeProcessor.java`
- [Game data](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gamification/src/main/java/microservices/book/gamification/game/ScoreRepository.java): domain + repo · Score and badge persistence boundary · `gamification/src/main/java/microservices/book/gamification/game/ScoreRepository.java`

### Platform

Container, config, event, and log plumbing

- [Logs service](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/logs/src/main/java/microservices/book/logs/LogsConsumer.java): Kafka consumer · Aggregates application logs from all services · `logs/src/main/java/microservices/book/logs/LogsConsumer.java`
- [Kafka logging](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/gateway/src/main/java/logback/kafka/KafkaAppenderWithHeader.java): logback appender · Shared Kafka appenders and keying strategy used by services · `gateway/src/main/java/logback/kafka/KafkaAppenderWithHeader.java`
- [Consul bootstrap](https://github.com/bryanxtong/learnmicroserviceswithspringboot-kafka/blob/main/docker/consul/consul-kv-docker.json): infra config · Service registration and configuration bootstrap via Docker · `docker/consul/consul-kv-docker.json`

## Connections

- Challenge UI → Challenge screen: renders · UI shell composes the challenge screen
- Challenge UI → Last attempts: renders · UI shell composes recent attempts
- Challenge UI → Leaderboard: renders · UI shell composes leaderboard
- Challenge screen → Challenge API client: calls · Challenge screen submits and fetches gameplay data
- Leaderboard → Game API client: calls · Leaderboard UI reads game data
- Last attempts → Challenge API client: calls · Attempts widget reads challenge history
- Challenge API client → Gateway: routes via · Frontend API traffic enters through the gateway
- Game API client → Gateway: routes via · Frontend game traffic enters through the gateway
- Gateway → Challenge APIs: routes to · Gateway forwards gameplay requests
- Gateway → Leaderboard service: routes to · Gateway forwards leaderboard requests
- Challenge APIs → Challenge service: delegates · HTTP controllers hand off gameplay logic
- Challenge service → Challenge generator: uses · Service generates and evaluates multiplication challenges
- Challenge service → Challenge data: stores · Service persists challenges, attempts, and users
- Challenge service → Challenge solved event: publishes · Solved attempts become challenge-solved events
- Game handler → Challenge solved event: consumes · Gamification listens for solved-challenge events
- Game handler → Game service: delegates · Event handler applies reward logic
- Game service → Badge rules: applies · Badge processors decide earned rewards
- Game service → Game data: updates · Service persists score and badge state
- Leaderboard service → Game data: reads · Leaderboard queries derived game state
- Logs service → Kafka logging: receives from · Log consumer collects messages produced through Kafka appenders
- Challenge APIs → Kafka logging: emits logs · Multiplication service ships logs through the shared appender
- Game handler → Kafka logging: emits logs · Gamification service ships logs through the shared appender
- Gateway → Kafka logging: emits logs · Gateway ships logs through the shared appender
- Consul bootstrap → Gateway: registers/configures · Consul provides discovery and externalized config
- Consul bootstrap → Challenge APIs: registers/configures · Consul provides discovery and externalized config
- Consul bootstrap → Game handler: registers/configures · Consul provides discovery and externalized config
