How remoweirich/sopra-fs26-group-15-server works
1. This is a Spring Boot backend written in Java 17 and built with Gradle. The application entry point is Application.java, and the repo is organized as a layered server rather than a full-stack app.
2. The API surface is split into two transport mechanisms: classic REST controllers and a WebSocket endpoint. REST is used for user, lobby, and game HTTP operations; WebSocket is used for live lobby/game updates and message exchange.
3. The main domain is a multiplayer game around users, lobbies, rounds, scores, and train/station data. The objects package contains the core game model (Game, Lobby, Round, Score, Train, Station, LineString, UserGameStatus, Admin, GuessMessage), while constant defines state and type enums such as LobbyState, LobbyVisibility, UserStatus, and MessageType.
4. Controllers are the transport boundary. UserController, LobbyRESTController, and GameController handle HTTP requests, while LobbyWebSocketController handles real-time messages. These controllers should be treated as thin adapters that delegate to services and map to/from DTOs.
5. The service layer contains the business logic and orchestration: UserService, LobbyService, GameService, and GameTrainsService. This is where application rules, state transitions, and cross-object coordination are likely implemented.
6. Data access is intentionally narrow. The visible persistence boundary is UserRepository, with User and UserScoreboard as the main persistence-oriented entities. The repo does not show a broad database layer, so most game/lobby state appears to be managed in application memory or within the service/domain layer.
7. Request and response contracts are separated from domain objects through DTOs in rest/dto. DTOMapper converts between DTOs and the internal model. This keeps the REST API stable even if the game model changes.
8. Authentication and authorization are lightweight and header-based. AuthHeader and AuthService suggest token/user identity is carried in HTTP headers rather than a separate session system. DTOs such as LoginPostDTO, RegisterPostDTO, and UserAuthDTO support that flow.
9. Real-time behavior is a first-class subsystem. WebSocketConfig and websocket/Message define the socket channel, while MessageType standardizes event kinds. This is likely used to push lobby/game state changes to connected clients without polling.
10. The game depends on train position data. trains/TrainPositionFetcher and src/main/resources/mock_train_messages.json indicate an external or simulated train-position source. GameTrainsService likely bridges that data into the game loop, making train updates part of gameplay rather than a separate utility.
11. Cross-cutting concerns are centralized. GlobalExceptionAdvice provides unified API error handling, and JacksonConfig customizes JSON serialization/deserialization for the REST/WebSocket payloads.
12. The repository includes substantial support for testing and delivery. There are unit and integration tests for controllers, services, repositories, DTO mapping, and train fetching. CI/CD is set up with GitHub Actions workflows, and deployment is containerized via Dockerfile with an app.yaml also present for platform deployment.
13. If you draw an architecture diagram, the main flow is: client requests enter REST/WebSocket controllers, which call services, which operate on domain objects and repository-backed user data, while train-position data is fetched separately and fed into the game service. Exception handling and JSON configuration sit across the top as shared infrastructure.
Main entry points: GameService.java Game service · Application.java Application · LobbyWebSocketController.java Lobby socket · UserController.java User API
Components 21
Boot & infra
Application startup and shared infrastructure
- Application · Main Spring Boot startup entry point
src/main/java/ch/uzh/ifi/hase/soprafs26/Application.java - Jackson config · Custom JSON serialization/deserialization setup
src/main/java/ch/uzh/ifi/hase/soprafs26/config/JacksonConfig.java - Error advice · Centralized exception-to-response handling
src/main/java/ch/uzh/ifi/hase/soprafs26/exceptions/GlobalExceptionAdvice.java - Auth header · Header-based identity/token extraction
src/main/java/ch/uzh/ifi/hase/soprafs26/security/AuthHeader.java - Auth service · Authentication and authorization helper service
src/main/java/ch/uzh/ifi/hase/soprafs26/security/AuthService.java
API boundary
HTTP and WebSocket transport adapters
- User API · HTTP endpoints for users and auth
src/main/java/ch/uzh/ifi/hase/soprafs26/controller/UserController.java - Lobby API · HTTP endpoints for lobby creation and updates
src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyRESTController.java - Game API · HTTP endpoints for game operations
src/main/java/ch/uzh/ifi/hase/soprafs26/controller/GameController.java - Lobby socket · Real-time lobby and game message endpoint
src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyWebSocketController.java - DTO mapper · Converts between REST DTOs and domain objects
src/main/java/ch/uzh/ifi/hase/soprafs26/rest/mapper/DTOMapper.java - Socket message · Real-time message envelope for the socket channel
src/main/java/ch/uzh/ifi/hase/soprafs26/websocket/Message.java
Services
Business logic and orchestration
- User service · User lifecycle and auth-related orchestration
src/main/java/ch/uzh/ifi/hase/soprafs26/service/UserService.java - Lobby service · Lobby state management and coordination
src/main/java/ch/uzh/ifi/hase/soprafs26/service/LobbyService.java - Game service · Game rules, rounds, scores, and state transitions
src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameService.java - Train sync · Bridges train-position data into gameplay
src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameTrainsService.java
Domain model
Core game and user objects
- Game model · Core game objects such as game, lobby, round, score, train, station, and statuses
src/main/java/ch/uzh/ifi/hase/soprafs26/objects/Game.java - Enums · State and message enums used across the application
src/main/java/ch/uzh/ifi/hase/soprafs26/constant/MessageType.java
Data access
Persistence and external data sources
- User repo · Persistence boundary for user data
src/main/java/ch/uzh/ifi/hase/soprafs26/repository/UserRepository.java - User entity · Stored user record
src/main/java/ch/uzh/ifi/hase/soprafs26/entity/User.java - Scoreboard · Stored user scoreboard projection
src/main/java/ch/uzh/ifi/hase/soprafs26/entity/UserScoreboard.java - Train fetcher · Loads or simulates train position messages
src/main/java/ch/uzh/ifi/hase/soprafs26/trains/TrainPositionFetcher.java
Connections 29
- Application → User API: starts · Bootstraps the HTTP user API
- Application → Lobby API: starts · Bootstraps the lobby REST API
- Application → Game API: starts · Bootstraps the game REST API
- Application → Lobby socket: starts · Bootstraps the WebSocket endpoint
- User API → User service: delegates · Controller hands off user operations
- Lobby API → Lobby service: delegates · Controller hands off lobby operations
- Game API → Game service: delegates · Controller hands off game operations
- Lobby socket → Lobby service: publishes · Real-time lobby actions go through lobby state logic
- Lobby socket → Game service: publishes · Real-time game actions go through game state logic
- User API → DTO mapper: maps · Converts request/response DTOs
- Lobby API → DTO mapper: maps · Converts lobby DTOs
- Game API → DTO mapper: maps · Converts game DTOs
- Lobby socket → Socket message: formats · Uses a socket message envelope
- User service → Auth service: uses · Validates identity and access
- User service → User repo: persists · Reads and writes user records
- User repo → User entity: stores · Repository is backed by user entity
- User repo → Scoreboard: stores · Repository also works with scoreboard data
- Lobby service → Game model: manages · Coordinates lobby and user game state
- Game service → Game model: manages · Runs game rounds, scores, and train/station logic
- Game service → Enums: uses · Relies on lobby, user, and message enums
- Lobby service → Enums: uses · Relies on lobby and user state enums
- Train sync → Train fetcher: consumes · Pulls or simulates train-position updates
- Train sync → Game service: feeds · Injects train updates into game progression
- Auth service → Auth header: reads · Extracts identity from headers
- Error advice → User API: covers · Applies shared API error handling
- Error advice → Lobby API: covers · Applies shared API error handling
- Error advice → Game API: covers · Applies shared API error handling
- Jackson config → DTO mapper: supports · Serialization setup complements DTO mapping
- Jackson config → Socket message: supports · Configures JSON payload handling for sockets