How dantomaz/guess-who works
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).