# duyphuc0701/quizmaster-backend architecture

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

- Interactive diagram: https://gitdiagram.com/duyphuc0701/quizmaster-backend
- Repository: https://github.com/duyphuc0701/quizmaster-backend

## Overview

1. **System shape**
   - QuizMaster is a single Spring Boot 3 / Java 17+ backend organized as a layered monolith.
   - It combines three main interaction styles: REST APIs for management, WebSockets for live gameplay, and static HTML/JS pages for manual host/player testing.

2. **External infrastructure**
   - The repo is designed to run with Docker Compose alongside **PostgreSQL** and **Keycloak**.
   - Keycloak provides identity, OAuth2/OIDC, and role-based access; PostgreSQL is the system of record for quizzes, sessions, players, and answers.
   - The `init-scripts` directory suggests startup database preparation, likely for multiple schemas/databases used by the app and auth infrastructure.

3. **Security boundary**
   - Security is centered in `SecurityConfig` and `KeycloakConfig`.
   - The backend acts as a protected resource server and trusts Keycloak-issued JWTs.
   - The README indicates role-based access control, with at least one privileged role (`manage-user`) for administrative operations.

4. **HTTP API layer**
   - `QuizController`, `GameSessionController`, `GameplayController`, and `UserController` form the REST entry points.
   - These controllers separate concerns by domain: quiz management, game-session lifecycle, player/game actions, and user/profile handling.
   - Controllers return DTOs rather than entities, which keeps API contracts decoupled from persistence.

5. **Real-time gameplay layer**
   - `WebSocketConfig` enables STOMP/SockJS messaging for live multiplayer interactions.
   - This is the main low-latency path for gameplay events: player joins, question broadcasts, answer submissions, timers, and leaderboard updates.
   - The DTOs named `QuestionBroadcastDto`, `RevealAnswerDto`, `SessionEventDto`, and `LeaderboardEntryDto` indicate event-driven message exchange over WebSocket.

6. **Domain model**
   - The core quiz domain includes `Quiz`, `Question`, and `Option`.
   - The live-game domain includes `GameSession`, `Player`, `PlayerAnswer`, and `QuizAttempt`.
   - User/account-related state is represented by `User`, with separate DTOs for profile and auth flow.

7. **Business services**
   - `QuizService`, `GameSessionService`, and `UserService` contain the business rules and orchestration.
   - These services likely coordinate persistence, validation, session state transitions, scoring, and authorization checks.
   - The presence of session/status enums (`SessionStatus`, `AttemptStatus`) shows explicit lifecycle management in the service layer.

8. **Persistence layer**
   - Spring Data JPA repositories (`QuizRepository`, `GameSessionRepository`, `PlayerRepository`, `PlayerAnswerRepository`, etc.) provide database access.
   - The repository boundaries map closely to aggregates, suggesting the application stores quiz content separately from runtime game state and player responses.
   - Hibernate/JPA is the abstraction between domain entities and PostgreSQL.

9. **Data flow for a game**
   - A host first creates or starts a `GameSession` using a quiz ID and authenticated access.
   - Players join the session using a game PIN, creating `Player` records tied to that session.
   - During gameplay, the host advances questions, the backend broadcasts the question to all players, players submit answers, and the backend computes and reveals results/leaderboards in real time.

10. **Static frontend as a test harness**
   - `host.html` and `player.html` are bundled in `src/main/resources/static` and served directly by the backend.
   - The accompanying JS files (`main.js`, `game-logic.js`, `stomp-client.js`) act as a lightweight client for exercising REST and WebSocket flows.
   - This is not a separate frontend application; it is an embedded, minimal UI for operational testing and demos.

11. **Configuration and integration**
   - `WebClientConfig` indicates at least one outbound HTTP client is configured, likely for integration or token-related calls.
   - `application.properties` centralizes runtime wiring such as DB, Keycloak, and server settings.
   - Swagger UI is enabled for API exploration, which supports the repository’s API-first backend workflow.

12. **Operational boundaries**
   - Error handling is centralized via `ApiException` and `GlobalExceptionHandler`, keeping REST failures consistent.
   - The architecture clearly separates: security/authentication, quiz administration, session orchestration, real-time gameplay messaging, and persistence.
   - For a diagram, the key edges are: browser/static client → REST/WebSocket endpoints → service layer → JPA repositories → PostgreSQL, with Keycloak as the external auth provider.

Main entry points: [`src/main/java/com/example/quizmaster/controller`](https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/java/com/example/quizmaster/controller) (REST API), [`src/main/java/com/example/quizmaster/service/GameSessionService.java`](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/service/GameSessionService.java) (Session service), [`src/main/java/com/example/quizmaster/QuizmasterApplication.java`](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/QuizmasterApplication.java) (QuizMaster), [`src/main/java/com/example/quizmaster/repository`](https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/java/com/example/quizmaster/repository) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_interfaces["Interfaces"]
  node_node_websocket["WebSocket<br/>stomp messaging"]
  node_node_rest["REST API<br/>controllers"]
  node_node_quiz_controller["Quiz API<br/>quiz controller"]
  node_node_session_controller["Session API<br/>session controller"]
  node_node_gameplay_controller["Gameplay API<br/>gameplay controller"]
  node_node_user_controller["User API<br/>user controller"]
  node_node_static_ui["Static UI<br/>embedded client"]
end

subgraph group_group_core["Core app"]
  node_node_app(("QuizMaster<br/>Spring Boot app"))
  node_node_security["Security<br/>resource server"]
  node_node_keycloak["Keycloak config<br/>oidc integration"]
  node_node_quiz_service["Quiz service<br/>business service<br/>[QuizService.java]"]
  node_node_session_service["Session service<br/>orchestration service"]
  node_node_user_service["User service<br/>account service<br/>[UserService.java]"]
  node_node_domain_quiz["Quiz model<br/>quiz entities<br/>[Quiz.java]"]
  node_node_domain_session["Game model<br/>game entities<br/>[GameSession.java]"]
  node_node_domain_user["User model<br/>account entity<br/>[User.java]"]
  node_node_errors["Errors<br/>exception handling"]
  node_node_config["App config<br/>runtime config"]
end

subgraph group_group_infra["Infrastructure"]
  node_node_repos[("Repositories")]
  node_node_db[("PostgreSQL<br/>database")]
  node_node_keycloak_ext[("Keycloak<br/>identity provider")]
end

node_node_app -->|"loads"| node_node_security
node_node_app -->|"enables"| node_node_websocket
node_node_app -->|"exposes"| node_node_rest
node_node_app -->|"reads"| node_node_config
node_node_security -->|"trusts"| node_node_keycloak_ext
node_node_keycloak -->|"integrates with"| node_node_keycloak_ext
node_node_rest -->|"contains"| node_node_quiz_controller
node_node_rest -->|"contains"| node_node_session_controller
node_node_rest -->|"contains"| node_node_gameplay_controller
node_node_rest -->|"contains"| node_node_user_controller
node_node_quiz_controller -->|"calls"| node_node_quiz_service
node_node_session_controller -->|"calls"| node_node_session_service
node_node_gameplay_controller -->|"calls"| node_node_session_service
node_node_user_controller -->|"calls"| node_node_user_service
node_node_quiz_service -->|"operates on"| node_node_domain_quiz
node_node_session_service -->|"operates on"| node_node_domain_session
node_node_user_service -->|"operates on"| node_node_domain_user
node_node_quiz_service -->|"persists via"| node_node_repos
node_node_session_service -->|"persists via"| node_node_repos
node_node_user_service -->|"persists via"| node_node_repos
node_node_repos -->|"reads/writes"| node_node_db
node_node_static_ui -->|"uses"| node_node_rest
node_node_static_ui -->|"uses"| node_node_websocket
node_node_session_service -->|"raises"| node_node_errors
node_node_rest -->|"handled by"| node_node_errors

click node_node_app "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/QuizmasterApplication.java"
click node_node_security "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/config/SecurityConfig.java"
click node_node_keycloak "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/config/KeycloakConfig.java"
click node_node_websocket "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/config/WebSocketConfig.java"
click node_node_rest "https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/java/com/example/quizmaster/controller"
click node_node_quiz_controller "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/QuizController.java"
click node_node_session_controller "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/GameSessionController.java"
click node_node_gameplay_controller "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/GameplayController.java"
click node_node_user_controller "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/UserController.java"
click node_node_quiz_service "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/service/QuizService.java"
click node_node_session_service "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/service/GameSessionService.java"
click node_node_user_service "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/service/UserService.java"
click node_node_domain_quiz "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/entity/Quiz.java"
click node_node_domain_session "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/entity/GameSession.java"
click node_node_domain_user "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/entity/User.java"
click node_node_repos "https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/java/com/example/quizmaster/repository"
click node_node_static_ui "https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/resources/static"
click node_node_errors "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/exception/GlobalExceptionHandler.java"
click node_node_config "https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/resources/application.properties"

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_websocket,node_node_rest,node_node_quiz_controller,node_node_session_controller,node_node_gameplay_controller,node_node_user_controller,node_node_static_ui toneBlue
class node_node_app,node_node_security,node_node_keycloak,node_node_quiz_service,node_node_session_service,node_node_user_service,node_node_domain_quiz,node_node_domain_session,node_node_domain_user,node_node_errors,node_node_config toneAmber
class node_node_repos,node_node_db,node_node_keycloak_ext toneMint
```

## Components

### Interfaces

HTTP, WebSocket, and embedded static clients

- [WebSocket](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/config/WebSocketConfig.java): stomp messaging · Live gameplay messaging setup · `src/main/java/com/example/quizmaster/config/WebSocketConfig.java`
- [REST API](https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/java/com/example/quizmaster/controller): controllers · HTTP entry points for management, gameplay, and users · `src/main/java/com/example/quizmaster/controller`
- [Quiz API](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/QuizController.java): quiz controller · Quiz management endpoints · `src/main/java/com/example/quizmaster/controller/QuizController.java`
- [Session API](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/GameSessionController.java): session controller · Game session lifecycle endpoints · `src/main/java/com/example/quizmaster/controller/GameSessionController.java`
- [Gameplay API](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/GameplayController.java): gameplay controller · Player action endpoints during live play · `src/main/java/com/example/quizmaster/controller/GameplayController.java`
- [User API](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/controller/UserController.java): user controller · User and profile endpoints · `src/main/java/com/example/quizmaster/controller/UserController.java`
- [Static UI](https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/resources/static): embedded client · host/player HTML and JavaScript test harness · `src/main/resources/static`

### Core app

Security, controllers, services, domain, and exception flow

- [QuizMaster](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/QuizmasterApplication.java): Spring Boot app · Application entrypoint and overall backend bootstrap · `src/main/java/com/example/quizmaster/QuizmasterApplication.java`
- [Security](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/config/SecurityConfig.java): resource server · JWT/OIDC and role-based access boundary · `src/main/java/com/example/quizmaster/config/SecurityConfig.java`
- [Keycloak config](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/config/KeycloakConfig.java): oidc integration · Keycloak-specific auth and identity wiring · `src/main/java/com/example/quizmaster/config/KeycloakConfig.java`
- [Quiz service](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/service/QuizService.java): business service · Quiz creation and quiz-domain rules · `src/main/java/com/example/quizmaster/service/QuizService.java`
- [Session service](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/service/GameSessionService.java): orchestration service · Session state transitions, scoring, and live-game coordination · `src/main/java/com/example/quizmaster/service/GameSessionService.java`
- [User service](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/service/UserService.java): account service · User/profile logic and auth-related lookups · `src/main/java/com/example/quizmaster/service/UserService.java`
- [Quiz model](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/entity/Quiz.java): quiz entities · Quiz, question, and option data model · `src/main/java/com/example/quizmaster/entity/Quiz.java`
- [Game model](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/entity/GameSession.java): game entities · GameSession, Player, attempts, and answers · `src/main/java/com/example/quizmaster/entity/GameSession.java`
- [User model](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/entity/User.java): account entity · Application user state · `src/main/java/com/example/quizmaster/entity/User.java`
- [Errors](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/java/com/example/quizmaster/exception/GlobalExceptionHandler.java): exception handling · Central API error mapping and response shaping · `src/main/java/com/example/quizmaster/exception/GlobalExceptionHandler.java`
- [App config](https://github.com/duyphuc0701/quizmaster-backend/blob/main/src/main/resources/application.properties): runtime config · Application properties and outbound client wiring · `src/main/resources/application.properties`

### Infrastructure

Persistence and external systems

- [Repositories](https://github.com/duyphuc0701/quizmaster-backend/tree/main/src/main/java/com/example/quizmaster/repository): jpa repositories · Spring Data JPA access layer · `src/main/java/com/example/quizmaster/repository`
- **PostgreSQL**: database · System of record for quizzes and gameplay state
- **Keycloak**: identity provider · External OAuth2/OIDC and role authority source

## Connections

- QuizMaster → Security: loads · Bootstraps security boundary
- QuizMaster → WebSocket: enables · Registers real-time messaging support
- QuizMaster → REST API: exposes · Starts HTTP endpoints
- QuizMaster → App config: reads · Uses runtime configuration
- Security → Keycloak: trusts · Accepts Keycloak-issued tokens
- Keycloak config → Keycloak: integrates with · Configures external identity provider
- REST API → Quiz API: contains · Quiz management endpoints
- REST API → Session API: contains · Session lifecycle endpoints
- REST API → Gameplay API: contains · Gameplay endpoints
- REST API → User API: contains · User endpoints
- Quiz API → Quiz service: calls · Delegates quiz operations
- Session API → Session service: calls · Delegates session lifecycle operations
- Gameplay API → Session service: calls · Delegates live gameplay actions
- User API → User service: calls · Delegates user/profile operations
- Quiz service → Quiz model: operates on · Manages quiz aggregates
- Session service → Game model: operates on · Manages runtime game state
- User service → User model: operates on · Manages user accounts
- Quiz service → Repositories: persists via · Stores quiz content
- Session service → Repositories: persists via · Stores sessions and answers
- User service → Repositories: persists via · Stores user records
- Repositories → PostgreSQL: reads/writes · JPA persistence to PostgreSQL
- Static UI → REST API: uses · Exercises management APIs
- Static UI → WebSocket: uses · Connects to live gameplay channel
- Session service → Errors: raises · Business failures mapped to API errors
- REST API → Errors: handled by · REST exceptions translated consistently
