How bryanxtong/learnmicroserviceswithspringboot-kafka works
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: GatewayApplication.java Gateway · ChallengeServiceImpl.java Challenge service · GameEventHandler.java Game handler · ChallengeController.java Challenge APIs
Components 21
Frontend
Browser UI and API clients
- Challenge UI · Browser entry point for solving challenges, viewing attempts, and leaderboard
challenges-frontend/src/App.js - Challenge screen · Challenge solving widget
challenges-frontend/src/components/ChallengeComponent.js - Last attempts · Recent attempt history widget
challenges-frontend/src/components/LastAttemptsComponent.js - Leaderboard · Leaderboard widget
challenges-frontend/src/components/LeaderBoardComponent.js - Challenge API client · Frontend client for gameplay and attempt endpoints
challenges-frontend/src/services/ChallengeApiClient.js - Game API client · Frontend client for leaderboard and reward data
challenges-frontend/src/services/GameApiClient.js
Edge
API routing boundary
- 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 · Challenge and attempt HTTP entry points
multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeController.java - Challenge generator · Builds multiplication challenges and validates attempts
multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeGeneratorServiceImpl.java - Challenge service · Coordinates gameplay and attempt handling
multiplication/src/main/java/microservices/book/multiplication/challenge/ChallengeServiceImpl.java - User API · User management endpoint
multiplication/src/main/java/microservices/book/multiplication/user/UserController.java - Challenge data · Challenge, attempt, user, and persistence boundary
multiplication/src/main/java/microservices/book/multiplication/challenge/Challenge.java - Challenge solved event · Common event payload used between gameplay and gamification
multiplication/src/main/java/microservices/book/event/challenge/ChallengeSolvedEvent.java - Game handler · Consumes solved-challenge events
gamification/src/main/java/microservices/book/gamification/game/GameEventHandler.java - Game service · Awards badges and updates derived game state
gamification/src/main/java/microservices/book/gamification/game/GameServiceImpl.java - Leaderboard service · Serves leaderboard views and ranking data
gamification/src/main/java/microservices/book/gamification/game/LeaderBoardServiceImpl.java - Badge rules · First win, bronze, silver, gold, and lucky-number badge processors
gamification/src/main/java/microservices/book/gamification/game/badgeprocessors/BadgeProcessor.java - Game data · Score and badge persistence boundary
gamification/src/main/java/microservices/book/gamification/game/ScoreRepository.java
Platform
Container, config, event, and log plumbing
- Logs service · Aggregates application logs from all services
logs/src/main/java/microservices/book/logs/LogsConsumer.java - Kafka logging · Shared Kafka appenders and keying strategy used by services
gateway/src/main/java/logback/kafka/KafkaAppenderWithHeader.java - Consul bootstrap · Service registration and configuration bootstrap via Docker
docker/consul/consul-kv-docker.json
Connections 26
- 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