How duyphuc0701/quizmaster-backend works
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: controller REST API · GameSessionService.java Session service · QuizmasterApplication.java QuizMaster · repository Repositories
Components 21
Interfaces
HTTP, WebSocket, and embedded static clients
- WebSocket · Live gameplay messaging setup
src/main/java/com/example/quizmaster/config/WebSocketConfig.java - REST API · HTTP entry points for management, gameplay, and users
src/main/java/com/example/quizmaster/controller - Quiz API · Quiz management endpoints
src/main/java/com/example/quizmaster/controller/QuizController.java - Session API · Game session lifecycle endpoints
src/main/java/com/example/quizmaster/controller/GameSessionController.java - Gameplay API · Player action endpoints during live play
src/main/java/com/example/quizmaster/controller/GameplayController.java - User API · User and profile endpoints
src/main/java/com/example/quizmaster/controller/UserController.java - Static UI · host/player HTML and JavaScript test harness
src/main/resources/static
Core app
Security, controllers, services, domain, and exception flow
- QuizMaster · Application entrypoint and overall backend bootstrap
src/main/java/com/example/quizmaster/QuizmasterApplication.java - Security · JWT/OIDC and role-based access boundary
src/main/java/com/example/quizmaster/config/SecurityConfig.java - Keycloak config · Keycloak-specific auth and identity wiring
src/main/java/com/example/quizmaster/config/KeycloakConfig.java - Quiz service · Quiz creation and quiz-domain rules
src/main/java/com/example/quizmaster/service/QuizService.java - Session service · Session state transitions, scoring, and live-game coordination
src/main/java/com/example/quizmaster/service/GameSessionService.java - User service · User/profile logic and auth-related lookups
src/main/java/com/example/quizmaster/service/UserService.java - Quiz model · Quiz, question, and option data model
src/main/java/com/example/quizmaster/entity/Quiz.java - Game model · GameSession, Player, attempts, and answers
src/main/java/com/example/quizmaster/entity/GameSession.java - User model · Application user state
src/main/java/com/example/quizmaster/entity/User.java - Errors · Central API error mapping and response shaping
src/main/java/com/example/quizmaster/exception/GlobalExceptionHandler.java - App config · Application properties and outbound client wiring
src/main/resources/application.properties
Infrastructure
Persistence and external systems
- Repositories · Spring Data JPA access layer
src/main/java/com/example/quizmaster/repository - PostgreSQL · System of record for quizzes and gameplay state
- Keycloak · External OAuth2/OIDC and role authority source
Connections 25
- 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