# nikolaiunknown/tictactoe-server architecture

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

- Interactive diagram: https://gitdiagram.com/nikolaiunknown/tictactoe-server
- Repository: https://github.com/nikolaiunknown/tictactoe-server

## Overview

#### Purpose and Runtime
Spring Boot 3.5 / Java 21 backend for authenticated, real-time multiplayer Tic-Tac-Toe. It exposes REST for identity, game/history/profile operations and STOMP WebSocket for live play. Application bootstrap is `src/main/java/com/tictactoe/server/ServerApplication.java`; runtime settings, including game disconnect/rating parameters and JWT lifetime, are in `src/main/resources/application.yaml`.

#### Transport Entry Points
REST requests enter through `src/main/java/com/tictactoe/server/controllers/AuthController.java`, `src/main/java/com/tictactoe/server/controllers/GameController.java`, and `src/main/java/com/tictactoe/server/controllers/PlayerController.java`. Live client moves enter the WebSocket controller/handler pair at `src/main/java/com/tictactoe/server/controllers/GameHandler.java` and `src/main/java/com/tictactoe/server/config/WebSocketConfig.java`, using the documented `/ws/connect` endpoint and `/app/game/move` mapping. Separate global handlers normalize REST and WebSocket failures.

#### Authentication and Authorization Boundary
Spring Security protects HTTP and messaging traffic. JWT creation/validation is centered on `src/main/java/com/tictactoe/server/security/JwtCore.java`; HTTP bearer-token processing uses `src/main/java/com/tictactoe/server/security/JwtTokenFilter.java`, while STOMP connection/message authentication uses `src/main/java/com/tictactoe/server/security/AuthenticationChannelInterceptor.java`. Access and persisted refresh-token lifecycle flow through `src/main/java/com/tictactoe/server/services/RefreshTokenService.java` and `src/main/java/com/tictactoe/server/models/RefreshToken.java`.

#### Persistent Domain and Service Layer
MySQL-backed JPA entities represent players, games, and refresh tokens in `src/main/java/com/tictactoe/server/models/Player.java`, `src/main/java/com/tictactoe/server/models/Game.java`, and `src/main/java/com/tictactoe/server/models/RefreshToken.java`. Repositories isolate persistence; service implementations own business workflows: game creation/cancellation and history, player profiles/statistics/ELO, and token management. DTO/mapping boundaries prevent entities from being direct API contracts, notably `src/main/java/com/tictactoe/server/mappers/GameMapper.java` and `src/main/java/com/tictactoe/server/mappers/PlayerMapper.java`.

#### Live Game State and Move Processing
The in-memory gameplay/session layer is distinct from persisted game records. `src/main/java/com/tictactoe/server/core/GameCore.java` holds board/rule logic, `src/main/java/com/tictactoe/server/core/GameSession.java` represents an active match, and `src/main/java/com/tictactoe/server/services/GameSessionService.java` coordinates session lifecycle. A move flows from STOMP handler to `src/main/java/com/tictactoe/server/services/GameMoveService.java`, where participant, turn, board-cell, and game-status validation precede state mutation, result handling, and game/player persistence updates.

#### Matchmaking, Messaging, and Disconnect Lifecycle
Unstarted games/invitations and disconnected participants are managed independently by `src/main/java/com/tictactoe/server/core/UnstartedGamesManager.java` and `src/main/java/com/tictactoe/server/core/DisconnectedPlayersManager.java`. Outbound game/session/proposition messages are published through `src/main/java/com/tictactoe/server/services/WebSocketMessagingService.java`; message caching supports connection/session continuity via `src/main/java/com/tictactoe/server/services/MessageCacheService.java`. `src/main/java/com/tictactoe/server/utils/WebSocketEventListener.java` observes connection events, while `src/main/java/com/tictactoe/server/utils/ScheduleTasks.java` enforces delayed disconnect cancellation.

#### Infrastructure
Gradle builds and runs the service (`build.gradle`), and `Dockerfile` packages it for container deployment. Material external dependencies are MySQL via Spring Data JPA/Hibernate and client WebSocket/STOMP connections; there is no separate broker or cache service indicated by the repository.

Main entry points: [`src/main/java/com/tictactoe/server/services/GameMoveService.java`](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/GameMoveService.java) (Move service), [`src/main/java/com/tictactoe/server/controllers/AuthController.java`](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/controllers/AuthController.java) (REST controllers), [`src/main/java/com/tictactoe/server/services/WebSocketMessagingService.java`](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/WebSocketMessagingService.java) (WebSocket messaging), [`src/main/java/com/tictactoe/server/config/WebSocketConfig.java`](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/config/WebSocketConfig.java) (STOMP WebSocket)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app{{"Spring Boot app<br/>bootstrap"}}
end

subgraph group_transport["Transport"]
  node_rest["REST controllers<br/>HTTP API"]
  node_ws_config["STOMP WebSocket<br/>WebSocket config"]
  node_game_handler["Game handler<br/>STOMP handler<br/>[GameHandler.java]"]
end

subgraph group_security["Security"]
  node_jwt_core["JWT core<br/>token service<br/>[JwtCore.java]"]
  node_http_filter["Bearer filter<br/>HTTP security filter"]
  node_stomp_auth["STOMP auth interceptor<br/>message security"]
  node_refresh_tokens["Refresh token service<br/>token lifecycle"]
end

subgraph group_domain["Domain &amp; Persistence"]
  node_api_services["Game &amp; player services<br/>business services"]
  node_mappers["DTO mappers<br/>API mapping<br/>[GameMapper.java]"]
  node_entities["JPA domain entities<br/>[Game.java]"]
end

subgraph group_live["Live Gameplay"]
  node_sessions["Game session service<br/>session lifecycle"]
  node_game_core["Game core<br/>rules engine<br/>[GameCore.java]"]
  node_moves["Move service<br/>move workflow"]
  node_matchmaking["Matchmaking managers<br/>in-memory matchmaking"]
  node_messaging["WebSocket messaging<br/>outbound messaging"]
  node_message_cache["Message cache<br/>session continuity"]
  node_ws_events["Connection lifecycle<br/>event listener &amp; scheduler"]
end

subgraph group_infra["Infrastructure"]
  node_mysql[("MySQL<br/>database")]
  node_deployment["Gradle &amp; container build<br/>build/deployment<br/>[build.gradle]"]
end

node_app -->|"starts"| node_rest
node_app -->|"configures"| node_ws_config
node_rest -->|"secured by"| node_http_filter
node_http_filter -->|"validates bearer JWT"| node_jwt_core
node_ws_config -->|"intercepts messages"| node_stomp_auth
node_stomp_auth -->|"authenticates JWT"| node_jwt_core
node_rest -->|"issues/refreshes tokens"| node_refresh_tokens
node_refresh_tokens -->|"manages token entity"| node_entities
node_rest -->|"invokes"| node_api_services
node_api_services -->|"maps DTOs"| node_mappers
node_api_services -->|"reads/writes"| node_entities
node_entities -->|"persisted in"| node_mysql
node_ws_config -->|"routes move commands"| node_game_handler
node_game_handler -->|"submits move"| node_moves
node_moves -->|"loads active session"| node_sessions
node_moves -->|"validates and applies"| node_game_core
node_moves -->|"persists results and ratings"| node_api_services
node_moves -->|"publishes outcome"| node_messaging
node_sessions -->|"publishes session events"| node_messaging
node_matchmaking -->|"publishes invitations"| node_messaging
node_messaging -->|"caches messages"| node_message_cache
node_ws_events -->|"handles disconnects"| node_matchmaking
node_ws_events -->|"cancels delayed matches"| node_sessions
node_deployment -.->|"builds and packages"| node_app

click node_app "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/ServerApplication.java"
click node_rest "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/controllers/AuthController.java"
click node_ws_config "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/config/WebSocketConfig.java"
click node_game_handler "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/controllers/GameHandler.java"
click node_jwt_core "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/security/JwtCore.java"
click node_http_filter "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/security/JwtTokenFilter.java"
click node_stomp_auth "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/security/AuthenticationChannelInterceptor.java"
click node_refresh_tokens "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/RefreshTokenService.java"
click node_mappers "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/mappers/GameMapper.java"
click node_entities "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/models/Game.java"
click node_sessions "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/GameSessionService.java"
click node_game_core "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/core/GameCore.java"
click node_moves "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/GameMoveService.java"
click node_matchmaking "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/core/UnstartedGamesManager.java"
click node_messaging "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/WebSocketMessagingService.java"
click node_message_cache "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/MessageCacheService.java"
click node_ws_events "https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/utils/WebSocketEventListener.java"
click node_deployment "https://github.com/nikolaiunknown/tictactoe-server/blob/main/build.gradle"

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_app toneBlue
class node_rest,node_ws_config,node_game_handler toneAmber
class node_jwt_core,node_http_filter,node_stomp_auth,node_refresh_tokens toneMint
class node_api_services,node_mappers,node_entities toneRose
class node_sessions,node_game_core,node_moves,node_matchmaking,node_messaging,node_message_cache,node_ws_events toneIndigo
class node_mysql,node_deployment toneTeal
```

## Components

### Runtime

- [Spring Boot app](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/ServerApplication.java): bootstrap · `src/main/java/com/tictactoe/server/ServerApplication.java`

### Transport

- [REST controllers](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/controllers/AuthController.java): HTTP API · Auth, game, and player endpoints. · `src/main/java/com/tictactoe/server/controllers/AuthController.java`
- [STOMP WebSocket](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/config/WebSocketConfig.java): WebSocket config · Exposes /ws/connect and application message routing. · `src/main/java/com/tictactoe/server/config/WebSocketConfig.java`
- [Game handler](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/controllers/GameHandler.java): STOMP handler · Receives /app/game/move commands. · `src/main/java/com/tictactoe/server/controllers/GameHandler.java`

### Security

- [JWT core](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/security/JwtCore.java): token service · `src/main/java/com/tictactoe/server/security/JwtCore.java`
- [Bearer filter](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/security/JwtTokenFilter.java): HTTP security filter · `src/main/java/com/tictactoe/server/security/JwtTokenFilter.java`
- [STOMP auth interceptor](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/security/AuthenticationChannelInterceptor.java): message security · `src/main/java/com/tictactoe/server/security/AuthenticationChannelInterceptor.java`
- [Refresh token service](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/RefreshTokenService.java): token lifecycle · Manages persisted refresh tokens. · `src/main/java/com/tictactoe/server/services/RefreshTokenService.java`

### Domain & Persistence

- **Game & player services**: business services · Creation, history, profiles, statistics, and ELO workflows.
- [DTO mappers](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/mappers/GameMapper.java): API mapping · Keeps JPA entities out of API contracts. · `src/main/java/com/tictactoe/server/mappers/GameMapper.java`
- [JPA domain entities](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/models/Game.java): entities · Players, games, and refresh tokens. · `src/main/java/com/tictactoe/server/models/Game.java`

### Live Gameplay

- [Game session service](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/GameSessionService.java): session lifecycle · Coordinates active match sessions. · `src/main/java/com/tictactoe/server/services/GameSessionService.java`
- [Game core](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/core/GameCore.java): rules engine · In-memory board and rule logic. · `src/main/java/com/tictactoe/server/core/GameCore.java`
- [Move service](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/GameMoveService.java): move workflow · Validates moves, mutates state, resolves results, and persists updates. · `src/main/java/com/tictactoe/server/services/GameMoveService.java`
- [Matchmaking managers](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/core/UnstartedGamesManager.java): in-memory matchmaking · Tracks invitations and disconnected players. · `src/main/java/com/tictactoe/server/core/UnstartedGamesManager.java`
- [WebSocket messaging](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/WebSocketMessagingService.java): outbound messaging · Publishes game, session, and proposition events. · `src/main/java/com/tictactoe/server/services/WebSocketMessagingService.java`
- [Message cache](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/services/MessageCacheService.java): session continuity · `src/main/java/com/tictactoe/server/services/MessageCacheService.java`
- [Connection lifecycle](https://github.com/nikolaiunknown/tictactoe-server/blob/main/src/main/java/com/tictactoe/server/utils/WebSocketEventListener.java): event listener & scheduler · Observes disconnects and cancels games after delay. · `src/main/java/com/tictactoe/server/utils/WebSocketEventListener.java`

### Infrastructure

- **MySQL**: database · Spring Data JPA/Hibernate persistence store.
- [Gradle & container build](https://github.com/nikolaiunknown/tictactoe-server/blob/main/build.gradle): build/deployment · `build.gradle`

## Connections

- Spring Boot app → REST controllers: starts
- Spring Boot app → STOMP WebSocket: configures
- REST controllers → Bearer filter: secured by
- Bearer filter → JWT core: validates bearer JWT
- STOMP WebSocket → STOMP auth interceptor: intercepts messages
- STOMP auth interceptor → JWT core: authenticates JWT
- REST controllers → Refresh token service: issues/refreshes tokens
- Refresh token service → JPA domain entities: manages token entity
- REST controllers → Game & player services: invokes
- Game & player services → DTO mappers: maps DTOs
- Game & player services → JPA domain entities: reads/writes
- JPA domain entities → MySQL: persisted in
- STOMP WebSocket → Game handler: routes move commands
- Game handler → Move service: submits move
- Move service → Game session service: loads active session
- Move service → Game core: validates and applies
- Move service → Game & player services: persists results and ratings
- Move service → WebSocket messaging: publishes outcome
- Game session service → WebSocket messaging: publishes session events
- Matchmaking managers → WebSocket messaging: publishes invitations
- WebSocket messaging → Message cache: caches messages
- Connection lifecycle → Matchmaking managers: handles disconnects
- Connection lifecycle → Game session service: cancels delayed matches
- Gradle & container build → Spring Boot app: builds and packages