# remoweirich/sopra-fs26-group-15-server architecture

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

- Interactive diagram: https://gitdiagram.com/remoweirich/sopra-fs26-group-15-server
- Repository: https://github.com/remoweirich/sopra-fs26-group-15-server

## Overview

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: [`src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameService.java`](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameService.java) (Game service), [`src/main/java/ch/uzh/ifi/hase/soprafs26/Application.java`](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/Application.java) (Application), [`src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyWebSocketController.java`](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyWebSocketController.java) (Lobby socket), [`src/main/java/ch/uzh/ifi/hase/soprafs26/controller/UserController.java`](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/UserController.java) (User API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_boot["Boot & infra"]
  node_n_app(("Application<br/>spring boot entry<br/>[Application.java]"))
  node_n_jackson["Jackson config<br/>json config<br/>[JacksonConfig.java]"]
  node_n_exceptions["Error advice<br/>api advice"]
  node_n_authheader["Auth header<br/>request auth<br/>[AuthHeader.java]"]
  node_n_authservice["Auth service<br/>auth logic<br/>[AuthService.java]"]
end

subgraph group_grp_api["API boundary"]
  node_n_userctl["User API<br/>rest controller"]
  node_n_lobbyrest["Lobby API<br/>rest controller"]
  node_n_gamectl["Game API<br/>rest controller"]
  node_n_wsctl["Lobby socket<br/>websocket controller"]
  node_n_dtomapper["DTO mapper<br/>mapping<br/>[DTOMapper.java]"]
  node_n_wsmsg["Socket message<br/>websocket payload<br/>[Message.java]"]
end

subgraph group_grp_service["Services"]
  node_n_usersvc["User service<br/>business service<br/>[UserService.java]"]
  node_n_lobbysvc["Lobby service<br/>business service<br/>[LobbyService.java]"]
  node_n_gamesvc["Game service<br/>business service<br/>[GameService.java]"]
  node_n_trainsvc["Train sync<br/>game integration"]
end

subgraph group_grp_domain["Domain model"]
  node_n_domain{{"Game model<br/>domain package<br/>[Game.java]"}}
  node_n_constants["Enums<br/>domain constants<br/>[MessageType.java]"]
end

subgraph group_grp_data["Data access"]
  node_n_userrepo[("User repo")]
  node_n_userentity["User entity<br/>persistence entity<br/>[User.java]"]
  node_n_scoreboard["Scoreboard<br/>persistence entity"]
  node_n_trainfetch["Train fetcher<br/>external source"]
end

node_n_app -->|"starts"| node_n_userctl
node_n_app -->|"starts"| node_n_lobbyrest
node_n_app -->|"starts"| node_n_gamectl
node_n_app -->|"starts"| node_n_wsctl
node_n_userctl -->|"delegates"| node_n_usersvc
node_n_lobbyrest -->|"delegates"| node_n_lobbysvc
node_n_gamectl -->|"delegates"| node_n_gamesvc
node_n_wsctl -->|"publishes"| node_n_lobbysvc
node_n_wsctl -->|"publishes"| node_n_gamesvc
node_n_userctl -->|"maps"| node_n_dtomapper
node_n_lobbyrest -->|"maps"| node_n_dtomapper
node_n_gamectl -->|"maps"| node_n_dtomapper
node_n_wsctl -->|"formats"| node_n_wsmsg
node_n_usersvc -->|"uses"| node_n_authservice
node_n_usersvc -->|"persists"| node_n_userrepo
node_n_userrepo -->|"stores"| node_n_userentity
node_n_userrepo -->|"stores"| node_n_scoreboard
node_n_lobbysvc -->|"manages"| node_n_domain
node_n_gamesvc -->|"manages"| node_n_domain
node_n_gamesvc -->|"uses"| node_n_constants
node_n_lobbysvc -->|"uses"| node_n_constants
node_n_trainsvc -->|"consumes"| node_n_trainfetch
node_n_trainsvc -->|"feeds"| node_n_gamesvc
node_n_authservice -->|"reads"| node_n_authheader
node_n_exceptions -.->|"covers"| node_n_userctl
node_n_exceptions -.->|"covers"| node_n_lobbyrest
node_n_exceptions -.->|"covers"| node_n_gamectl
node_n_jackson -.->|"supports"| node_n_dtomapper
node_n_jackson -.->|"supports"| node_n_wsmsg

click node_n_app "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/Application.java"
click node_n_jackson "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/config/JacksonConfig.java"
click node_n_exceptions "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/exceptions/GlobalExceptionAdvice.java"
click node_n_authheader "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/security/AuthHeader.java"
click node_n_authservice "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/security/AuthService.java"
click node_n_userctl "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/UserController.java"
click node_n_lobbyrest "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyRESTController.java"
click node_n_gamectl "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/GameController.java"
click node_n_wsctl "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyWebSocketController.java"
click node_n_usersvc "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/UserService.java"
click node_n_lobbysvc "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/LobbyService.java"
click node_n_gamesvc "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameService.java"
click node_n_trainsvc "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameTrainsService.java"
click node_n_dtomapper "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/rest/mapper/DTOMapper.java"
click node_n_domain "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/objects/Game.java"
click node_n_constants "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/constant/MessageType.java"
click node_n_userrepo "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/repository/UserRepository.java"
click node_n_userentity "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/entity/User.java"
click node_n_scoreboard "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/entity/UserScoreboard.java"
click node_n_trainfetch "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/trains/TrainPositionFetcher.java"
click node_n_wsmsg "https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/websocket/Message.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_n_app,node_n_jackson,node_n_exceptions,node_n_authheader,node_n_authservice toneBlue
class node_n_userctl,node_n_lobbyrest,node_n_gamectl,node_n_wsctl,node_n_dtomapper,node_n_wsmsg toneAmber
class node_n_usersvc,node_n_lobbysvc,node_n_gamesvc,node_n_trainsvc toneMint
class node_n_domain,node_n_constants toneRose
class node_n_userrepo,node_n_userentity,node_n_scoreboard,node_n_trainfetch toneIndigo
```

## Components

### Boot & infra

Application startup and shared infrastructure

- [Application](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/Application.java): spring boot entry · Main Spring Boot startup entry point · `src/main/java/ch/uzh/ifi/hase/soprafs26/Application.java`
- [Jackson config](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/config/JacksonConfig.java): json config · Custom JSON serialization/deserialization setup · `src/main/java/ch/uzh/ifi/hase/soprafs26/config/JacksonConfig.java`
- [Error advice](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/exceptions/GlobalExceptionAdvice.java): api advice · Centralized exception-to-response handling · `src/main/java/ch/uzh/ifi/hase/soprafs26/exceptions/GlobalExceptionAdvice.java`
- [Auth header](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/security/AuthHeader.java): request auth · Header-based identity/token extraction · `src/main/java/ch/uzh/ifi/hase/soprafs26/security/AuthHeader.java`
- [Auth service](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/security/AuthService.java): auth logic · 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](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/UserController.java): rest controller · HTTP endpoints for users and auth · `src/main/java/ch/uzh/ifi/hase/soprafs26/controller/UserController.java`
- [Lobby API](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyRESTController.java): rest controller · HTTP endpoints for lobby creation and updates · `src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyRESTController.java`
- [Game API](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/GameController.java): rest controller · HTTP endpoints for game operations · `src/main/java/ch/uzh/ifi/hase/soprafs26/controller/GameController.java`
- [Lobby socket](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyWebSocketController.java): websocket controller · Real-time lobby and game message endpoint · `src/main/java/ch/uzh/ifi/hase/soprafs26/controller/LobbyWebSocketController.java`
- [DTO mapper](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/rest/mapper/DTOMapper.java): mapping · Converts between REST DTOs and domain objects · `src/main/java/ch/uzh/ifi/hase/soprafs26/rest/mapper/DTOMapper.java`
- [Socket message](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/websocket/Message.java): websocket payload · 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](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/UserService.java): business service · User lifecycle and auth-related orchestration · `src/main/java/ch/uzh/ifi/hase/soprafs26/service/UserService.java`
- [Lobby service](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/LobbyService.java): business service · Lobby state management and coordination · `src/main/java/ch/uzh/ifi/hase/soprafs26/service/LobbyService.java`
- [Game service](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameService.java): business service · Game rules, rounds, scores, and state transitions · `src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameService.java`
- [Train sync](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/service/GameTrainsService.java): game integration · 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](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/objects/Game.java): domain package · 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](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/constant/MessageType.java): domain constants · 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](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/repository/UserRepository.java): repository · Persistence boundary for user data · `src/main/java/ch/uzh/ifi/hase/soprafs26/repository/UserRepository.java`
- [User entity](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/entity/User.java): persistence entity · Stored user record · `src/main/java/ch/uzh/ifi/hase/soprafs26/entity/User.java`
- [Scoreboard](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/entity/UserScoreboard.java): persistence entity · Stored user scoreboard projection · `src/main/java/ch/uzh/ifi/hase/soprafs26/entity/UserScoreboard.java`
- [Train fetcher](https://github.com/remoweirich/sopra-fs26-group-15-server/blob/main/src/main/java/ch/uzh/ifi/hase/soprafs26/trains/TrainPositionFetcher.java): external source · Loads or simulates train position messages · `src/main/java/ch/uzh/ifi/hase/soprafs26/trains/TrainPositionFetcher.java`

## Connections

- 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
