# dantomaz/guess-who architecture

> Architecture diagram of the GitHub repository dantomaz/guess-who, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dantomaz/guess-who
- Repository: https://github.com/dantomaz/guess-who

## Overview

##### Project type and purpose
- This is the backend service for a real-time multiplayer “Guess Who?” game.
- It’s a Spring Boot application exposing both RESTful APIs and STOMP-over-WebSocket endpoints, managing rooms, players, game state, and user-uploaded images.
- It uses in-memory data structures for game logic, Spring Session with Redis for session management, and AWS S3 (or a localstack S3 emulation) for storing images.

##### File structure
- Top-level: Dockerfile, docker-compose.yaml, AWS Elastic Beanstalk config (`aws/.platform` and `Procfile`), Gradle build files, scripts for localstack.
- src/main/java/com/myapp/guess_who:
- Controllers: HealthCheck, RoomController, PlayerController, GameStateController
- Services: S3Service (image upload), FileService
- Core logic/managers: RoomManager, GameState, TeamState, Card, Activity
- Session: RedisSessionService, HttpSessionEventListener, WebSocketEventListener
- Configuration: WebConfig, WebSocketConfig, OpenAPIConfig
- Exception handling: REST and STOMP handlers, custom exceptions
- Validators, DTOs, utility classes
- src/main/resources: application.yaml (dev), application-prod.yaml, log4j2 configs.

##### README for additional insights
- REST + STOMP endpoints for room management, real-time updates, image uploads.
- No external relational database; game state is in memory.
- Spring Session + Redis for distributed session storage.
- Docker used for containerization; localstack script to emulate S3 locally.

##### Main components
a. Clients (e.g., guess-who-fe web or mobile app)
b. Reverse proxy / API gateway (AWS Nginx config or local Nginx in Docker Compose)
c. Spring Boot application
- HTTP/REST sub-component
- STOMP/WebSocket sub-component
- In-memory Game Engine (RoomManager + GameState)
- Image storage service (S3Service → S3 or localstack)
- Session service (Spring Session → Redis)
d. Redis (session store)
e. AWS S3 (or localstack S3)
f. Optional external services: health checks, logging (Log4j), monitoring (OpenAPI/Swagger).

##### Relationships and data flows
- Clients send HTTP calls to create/join rooms, upload images → API gateway → Spring Boot REST controllers → RoomManager/FileService → in-memory structures or S3.
- Clients establish WebSocket (STOMP) connections to subscribe to `/topic/gameState` (or similar) → Spring Boot WebSocket endpoints → GameStateController → broadcasts state changes via SimpMessagingTemplate.
- Session affinity: HTTP and WS sessions stored in Redis so multiple instances (if any) can share session data.
- File uploads: S3Service writes to AWS S3 (in prod) or localstack (in dev).

##### Architectural patterns and design principles
- Layered architecture: Controllers → Services → Domain (RoomManager, GameState)
- Event-driven real-time updates via STOMP/WebSocket
- Externalized configuration for environments (application-prod.yaml vs. application.yaml)
- Containerization for reproducible deployment (Dockerfile + docker-compose)
- Infrastructure-as-code for AWS (Elastic Beanstalk config under aws/.platform)
- Exception handling centralized via @ControllerAdvice for REST and WebSocket.

- Clear labels: component names and protocols (HTTP, WS/STOMP).
- Blue = external clients
- Green = application modules
- Orange = data stores
- Gray = infrastructure (proxy, containers)
- Notes or callouts for important constraints (in-memory state, no relational DB, uses Spring Session).

## Diagram (Mermaid)

```mermaid
graph TB
    client["Guess Who? Frontend"]:::client
    proxy["Nginx API Gateway"]:::infra

    subgraph "Spring Boot Application"
        entry["GuessWhoApplication"]:::app

        subgraph "REST API"
            health["HealthCheckController"]:::rest
            roomC["RoomController"]:::rest
            playerC["PlayerController"]:::rest
            gameStateC["GameStateController"]:::rest
        end

        subgraph "WebSocket/STOMP"
            wsConfig["WebSocketConfig"]:::config
            stompHandler["STOMP Endpoints"]:::ws
            simp["SimpMessagingTemplate"]:::ws
        end

        subgraph "Business Logic"
            roomMgr["RoomManager"]:::logic
            gameState["GameState"]:::logic
            teamState["TeamState"]:::logic
            card["Card"]:::logic
            activity["Activity"]:::logic
        end

        subgraph "Image Storage"
            s3Svc["S3Service"]:::service
            fileSvc["FileService"]:::service
        end

        subgraph "Session Management"
            redisSvc["RedisSessionService"]:::service
            httpListener["HttpSessionEventListener"]:::service
            wsListener["WebSocketEventListener"]:::service
        end

        subgraph "Configuration"
            webConfig["WebConfig"]:::config
            openApi["OpenAPIConfig"]:::config
        end

        subgraph "Exception Handling"
            restEx["RestExceptionHandler"]:::config
            stompEx["StompExceptionHandler"]:::config
        end

        subgraph "Validation & DTOs"
            roomVal["RoomValidator"]:::support
            playerVal["PlayerValidator"]:::support
            roomDTO["RoomDTO"]:::dto
            gameStateDTO["GameStateDTO"]:::dto
            toggleReq["ToggleCardRequest"]:::dto
            voteReq["VoteRequest"]:::dto
        end
    end

    redis["Redis (Session Store)"]:::db
    s3["AWS S3 (Images)"]:::db

    client -->|"HTTP/REST"| proxy
    client -->|"WS/STOMP"| proxy

    proxy -->|"GET /health"| health
    proxy -->|"POST /rooms"| roomC
    proxy -->|"POST /players"| playerC
    proxy -->|"POST /game/state"| gameStateC

    proxy -->|"CONNECT /ws"| wsConfig
    wsConfig --> stompHandler
    stompHandler -->|"/topic/gameState"| simp
    simp -->|"Message"| client

    roomC --> roomMgr
    playerC --> roomMgr
    gameStateC --> roomMgr
    roomMgr --> gameState
    gameState --> teamState
    gameState --> card
    gameState --> activity

    proxy -->|"POST /upload"| s3Svc
    s3Svc --> fileSvc
    fileSvc --> s3

    httpListener <-->|"Session Events"| redis
    wsListener <-->|"Session Events"| redis
    redisSvc <-->|"Reads/Writes"| redis

    entry --> health
    entry --> wsConfig
    entry --> webConfig

    classDef client fill:#D0E6FF,stroke:#0366d6
    classDef infra fill:#EDEDED,stroke:#888888
    classDef app fill:#DFFFE0,stroke:#2E8B57
    classDef rest fill:#E0FFE0,stroke:#2E8B57
    classDef ws fill:#E0FFF0,stroke:#2E8B57
    classDef logic fill:#F0FFF0,stroke:#228B22
    classDef service fill:#FFF0E0,stroke:#FF8C00
    classDef config fill:#F0F8FF,stroke:#1E90FF
    classDef support fill:#FFF5EE,stroke:#CD853F
    classDef dto fill:#FFF5F5,stroke:#FF69B4
    classDef db fill:#FFEFD5,stroke:#FF8C00

    click entry "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/GuessWhoApplication.java"
    click health "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/HealthCheckController.java"
    click roomC "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/room/RoomController.java"
    click playerC "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/player/PlayerController.java"
    click gameStateC "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/GameStateController.java"
    click wsConfig "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/configuration/WebSocketConfig.java"
    click roomMgr "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/room/RoomManager.java"
    click gameState "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/GameState.java"
    click teamState "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/TeamState.java"
    click card "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/Card.java"
    click activity "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/Activity.java"
    click s3Svc "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/api/S3Service.java"
    click fileSvc "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/storage/FileService.java"
    click redisSvc "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/session/RedisSessionService.java"
    click httpListener "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/session/HttpSessionEventListener.java"
    click wsListener "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/session/WebSocketEventListener.java"
    click webConfig "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/configuration/WebConfig.java"
    click openApi "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/configuration/OpenAPIConfig.java"
    click restEx "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/exception/handler/RestExceptionHandler.java"
    click stompEx "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/exception/handler/StompExceptionHandler.java"
    click roomVal "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/validator/RoomValidator.java"
    click playerVal "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/validator/PlayerValidator.java"
    click roomDTO "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/room/RoomDTO.java"
    click gameStateDTO "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/GameStateDTO.java"
    click toggleReq "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/request/ToggleCardRequest.java"
    click voteReq "https://github.com/dantomaz/guess-who/blob/master/src/main/java/com/myapp/guess_who/gameState/request/VoteRequest.java"
    click proxy "https://github.com/dantomaz/guess-who/blob/master/docker-compose.yaml"
    click proxy2 "https://github.com/dantomaz/guess-who/blob/master/aws/.platform/nginx/conf.d/proxy.conf"
    click dockerfile "https://github.com/dantomaz/guess-who/tree/master/Dockerfile"
    click awsPlatform "https://github.com/dantomaz/guess-who/tree/master/aws/.platform/"
    click procfile "https://github.com/dantomaz/guess-who/tree/master/aws/Procfile"
    click localstack "https://github.com/dantomaz/guess-who/blob/master/script/localstack/init-s3-bucket.sh"
```
