How nibinrj/buzzer works
Buzzer is a real-time multiplayer quiz platform. Hosts register or log in, author and publish a quiz, create a session, and share its room code; players join, receive questions over STOMP/WebSocket, and submit answers in a first-correct-buzz race. Session events flow through Kafka to scoring, whose leaderboard and final results are returned to clients. The README documents the cross-service integrations; sampled controllers and adapters ground the shown internal calls. Other internal wiring is not inferred where source was not sampled.
Main entry points: gateway API gateway · SessionController.java Session create and join · SubmitAnswer.java Live game state · ApplyScoringEvent.java Score application
Components 22
Entry and identity
- API gateway
services/gateway/src/main/java/dev/nibin/buzzer/gateway - Identity and tokens
services/identity-service/src/main/java/dev/nibin/buzzer/identity/api/AuthController.java
Quiz authoring
- Quiz authoring
services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/QuizController.java - Quiz rules
services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/domain/Quiz.java - Published snapshots
services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/InternalQuizController.java
Live sessions
- Session create and join
services/session-service/src/main/java/dev/nibin/buzzer/session/api/SessionController.java - Session lifecycle
services/session-service/src/main/java/dev/nibin/buzzer/session/domain/Session.java - Host game commands
services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/SessionCommandController.java - Answer and buzz
services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/AnswerController.java - Live game state
services/session-service/src/main/java/dev/nibin/buzzer/session/application/SubmitAnswer.java - Transactional event outbox
services/session-service/src/main/java/dev/nibin/buzzer/session/application/EventOutbox.java
Scoring and results
- Scoring event consumer
services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/kafka/ScoringEventListener.java - Score application
services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/application/ApplyScoringEvent.java - Results API
services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/api/ResultsController.java
Shared infrastructure
- Identity database
- Quiz database
services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/infrastructure/persistence/QuizJpaEntity.java - Session database
services/session-service/src/main/java/dev/nibin/buzzer/session/infrastructure/persistence/JpaSessionRepositoryAdapter.java - Redis state and fanout
- Kafka events
- Scoring database
services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/persistence/JdbcScoringRepository.java - Leaderboard cache
services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/redis/RedisLeaderboard.java
Other components
- Host and players
Connections 28
- Host and players → API gateway: HTTP and WebSocket
- API gateway → Identity and tokens: routes auth
- API gateway → Quiz authoring: routes quiz API
- API gateway → Session create and join: routes session API
- API gateway → Host game commands: routes STOMP
- API gateway → Answer and buzz: routes STOMP
- API gateway → Results API: routes results
- Identity and tokens → Identity database: stores accounts
- Quiz authoring → Quiz rules: applies quiz rules
services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/QuizController.java - Quiz authoring → Quiz database: persists quizzes
- Session create and join → Session lifecycle: creates sessions
services/session-service/src/main/java/dev/nibin/buzzer/session/api/SessionController.java - Session create and join → Published snapshots: requests snapshot
- Published snapshots → Session create and join: returns published quiz
services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/InternalQuizController.java - Session create and join → Session database: persists session
- Host game commands → Live game state: runs game
services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/SessionCommandController.java - Answer and buzz → Live game state: submits answer
services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/AnswerController.java - Live game state → Redis state and fanout: arbitrates buzz
- Live game state → Transactional event outbox: records events
- Transactional event outbox → Kafka events: publishes events
- Kafka events → Scoring event consumer: delivers events
- Scoring event consumer → Score application: applies events
- Score application → Scoring database: commits scores
- Score application → Leaderboard cache: updates leaderboard
- Results API → Score application: gets results
services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/api/ResultsController.java - Results API → Host and players: returns results
- Leaderboard cache → Session create and join: pushes updates
- Kafka events → Session create and join: delivers score updates
- Session database → Redis state and fanout: shares live state