# nibinrj/buzzer architecture

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

- Interactive diagram: https://gitdiagram.com/nibinrj/buzzer
- Repository: https://github.com/nibinrj/buzzer

## Overview

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: [`services/gateway/src/main/java/dev/nibin/buzzer/gateway`](https://github.com/nibinrj/buzzer/tree/main/services/gateway/src/main/java/dev/nibin/buzzer/gateway) (API gateway), [`services/session-service/src/main/java/dev/nibin/buzzer/session/api/SessionController.java`](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/api/SessionController.java) (Session create and join), [`services/session-service/src/main/java/dev/nibin/buzzer/session/application/SubmitAnswer.java`](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/application/SubmitAnswer.java) (Live game state), [`services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/application/ApplyScoringEvent.java`](https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/application/ApplyScoringEvent.java) (Score application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Entry and identity"]
  node_gateway["API gateway"]
  node_identity["Identity and tokens"]
end

subgraph group_content["Quiz authoring"]
  node_authoring["Quiz authoring"]
  node_quizdomain["Quiz rules<br/>[Quiz.java]"]
  node_snapshot["Published snapshots"]
end

subgraph group_game["Live sessions"]
  node_sessionapi["Session create and join"]
  node_sessiondomain["Session lifecycle<br/>[Session.java]"]
  node_commands["Host game commands"]
  node_answers["Answer and buzz"]
  node_live["Live game state<br/>[SubmitAnswer.java]"]
  node_outbox["Transactional event outbox<br/>[EventOutbox.java]"]
end

subgraph group_score["Scoring and results"]
  node_consumer["Scoring event consumer"]
  node_scoring["Score application"]
  node_results["Results API"]
end

subgraph group_infra["Shared infrastructure"]
  node_identitydb[("Identity database")]
  node_quizstore[("Quiz database<br/>[QuizJpaEntity.java]")]
  node_sessionstore[("Session database")]
  node_redis[("Redis state and fanout")]
  node_kafka["Kafka events"]
  node_scoringdb[("Scoring database")]
  node_leaderboard[("Leaderboard cache")]
end

node_clients(("Host and players"))

node_clients -->|"HTTP and WebSocket"| node_gateway
node_gateway -->|"routes auth"| node_identity
node_gateway -->|"routes quiz API"| node_authoring
node_gateway -->|"routes session API"| node_sessionapi
node_gateway -->|"routes STOMP"| node_commands
node_gateway -->|"routes STOMP"| node_answers
node_gateway -->|"routes results"| node_results
node_identity -.->|"stores accounts"| node_identitydb
node_authoring -->|"applies quiz rules"| node_quizdomain
node_authoring -.->|"persists quizzes"| node_quizstore
node_sessionapi -->|"creates sessions"| node_sessiondomain
node_sessionapi -.->|"requests snapshot"| node_snapshot
node_snapshot -->|"returns published quiz"| node_sessionapi
node_sessionapi -.->|"persists session"| node_sessionstore
node_commands -->|"runs game"| node_live
node_answers -->|"submits answer"| node_live
node_live -->|"arbitrates buzz"| node_redis
node_live -.->|"records events"| node_outbox
node_outbox -->|"publishes events"| node_kafka
node_kafka -->|"delivers events"| node_consumer
node_consumer -.->|"applies events"| node_scoring
node_scoring -->|"commits scores"| node_scoringdb
node_scoring -.->|"updates leaderboard"| node_leaderboard
node_results -->|"gets results"| node_scoring
node_results -->|"returns results"| node_clients
node_leaderboard -.->|"pushes updates"| node_sessionapi
node_kafka -.->|"delivers score updates"| node_sessionapi
node_sessionstore -.->|"shares live state"| node_redis

click node_gateway "https://github.com/nibinrj/buzzer/tree/main/services/gateway/src/main/java/dev/nibin/buzzer/gateway"
click node_identity "https://github.com/nibinrj/buzzer/blob/main/services/identity-service/src/main/java/dev/nibin/buzzer/identity/api/AuthController.java"
click node_authoring "https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/QuizController.java"
click node_quizdomain "https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/domain/Quiz.java"
click node_quizstore "https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/infrastructure/persistence/QuizJpaEntity.java"
click node_snapshot "https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/InternalQuizController.java"
click node_sessionapi "https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/api/SessionController.java"
click node_sessiondomain "https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/domain/Session.java"
click node_sessionstore "https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/infrastructure/persistence/JpaSessionRepositoryAdapter.java"
click node_commands "https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/SessionCommandController.java"
click node_answers "https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/AnswerController.java"
click node_live "https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/application/SubmitAnswer.java"
click node_outbox "https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/application/EventOutbox.java"
click node_consumer "https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/kafka/ScoringEventListener.java"
click node_scoring "https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/application/ApplyScoringEvent.java"
click node_scoringdb "https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/persistence/JdbcScoringRepository.java"
click node_leaderboard "https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/redis/RedisLeaderboard.java"
click node_results "https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/api/ResultsController.java"

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_gateway,node_identity toneBlue
class node_authoring,node_quizdomain,node_snapshot toneAmber
class node_sessionapi,node_sessiondomain,node_commands,node_answers,node_live,node_outbox toneMint
class node_consumer,node_scoring,node_results toneRose
class node_identitydb,node_quizstore,node_sessionstore,node_redis,node_kafka,node_scoringdb,node_leaderboard,node_clients toneIndigo
```

## Components

### Entry and identity

- [API gateway](https://github.com/nibinrj/buzzer/tree/main/services/gateway/src/main/java/dev/nibin/buzzer/gateway): `services/gateway/src/main/java/dev/nibin/buzzer/gateway`
- [Identity and tokens](https://github.com/nibinrj/buzzer/blob/main/services/identity-service/src/main/java/dev/nibin/buzzer/identity/api/AuthController.java): `services/identity-service/src/main/java/dev/nibin/buzzer/identity/api/AuthController.java`

### Quiz authoring

- [Quiz authoring](https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/QuizController.java): `services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/QuizController.java`
- [Quiz rules](https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/domain/Quiz.java): `services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/domain/Quiz.java`
- [Published snapshots](https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/InternalQuizController.java): `services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/api/InternalQuizController.java`

### Live sessions

- [Session create and join](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/api/SessionController.java): `services/session-service/src/main/java/dev/nibin/buzzer/session/api/SessionController.java`
- [Session lifecycle](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/domain/Session.java): `services/session-service/src/main/java/dev/nibin/buzzer/session/domain/Session.java`
- [Host game commands](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/SessionCommandController.java): `services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/SessionCommandController.java`
- [Answer and buzz](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/AnswerController.java): `services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/AnswerController.java`
- [Live game state](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/application/SubmitAnswer.java): `services/session-service/src/main/java/dev/nibin/buzzer/session/application/SubmitAnswer.java`
- [Transactional event outbox](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/application/EventOutbox.java): `services/session-service/src/main/java/dev/nibin/buzzer/session/application/EventOutbox.java`

### Scoring and results

- [Scoring event consumer](https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/kafka/ScoringEventListener.java): `services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/kafka/ScoringEventListener.java`
- [Score application](https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/application/ApplyScoringEvent.java): `services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/application/ApplyScoringEvent.java`
- [Results API](https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/api/ResultsController.java): `services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/api/ResultsController.java`

### Shared infrastructure

- **Identity database**
- [Quiz database](https://github.com/nibinrj/buzzer/blob/main/services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/infrastructure/persistence/QuizJpaEntity.java): `services/quiz-service/src/main/java/dev/nibin/buzzer/quiz/infrastructure/persistence/QuizJpaEntity.java`
- [Session database](https://github.com/nibinrj/buzzer/blob/main/services/session-service/src/main/java/dev/nibin/buzzer/session/infrastructure/persistence/JpaSessionRepositoryAdapter.java): `services/session-service/src/main/java/dev/nibin/buzzer/session/infrastructure/persistence/JpaSessionRepositoryAdapter.java`
- **Redis state and fanout**
- **Kafka events**
- [Scoring database](https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/persistence/JdbcScoringRepository.java): `services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/persistence/JdbcScoringRepository.java`
- [Leaderboard cache](https://github.com/nibinrj/buzzer/blob/main/services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/redis/RedisLeaderboard.java): `services/scoring-service/src/main/java/dev/nibin/buzzer/scoring/infrastructure/redis/RedisLeaderboard.java`

### Other components

- **Host and players**

## Connections

- 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 (evidence: `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 (evidence: `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 (evidence: `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 (evidence: `services/session-service/src/main/java/dev/nibin/buzzer/session/api/websocket/SessionCommandController.java`)
- Answer and buzz → Live game state: submits answer (evidence: `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 (evidence: `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
