akshansh029/chess-web

Purpose and entry points

Chess-Web is a two-process real-time multiplayer chess platform: a Next.js client and Spring Boot API/WebSocket server. Backend bootstraps at backend/src/main/java/com/akshansh/chessweb/ChessWebApplication.java; frontend App Router begins at frontend/src/app/layout.tsx and routes into lobby, authentication, profile, and game pages such as frontend/src/app/game/[id]/page.tsx.

Client application and state

The Next.js/React frontend renders the game experience and calls REST plus STOMP/SockJS endpoints. Authentication, active-game state, and notifications are held in context/store layers: frontend/src/context/AuthContext.tsx, frontend/src/context/GameContext.tsx, and frontend/src/services/chessStore.ts. Transport is centralized through frontend/src/services/api.ts and frontend/src/hooks/useWebSocket.ts, creating a boundary between UI and backend contracts.

Game-session UI

The live-game route composes board interaction, clocks/session display, chat, result presentation, and move history. Key components are frontend/src/components/game/GameSessionView.tsx, frontend/src/components/game/ChessBoardWrapper.tsx, and frontend/src/components/game/GameChat.tsx. Client chess libraries support board behavior, but submitted moves are not authoritative; the server validates and publishes resulting state.

HTTP, WebSocket, and security boundary

Spring controllers expose REST domains for auth, games, lobby, users, and chat through backend/src/main/java/com/akshansh/chessweb/controller/AuthController.java, backend/src/main/java/com/akshansh/chessweb/controller/GameController.java, and backend/src/main/java/com/akshansh/chessweb/controller/LobbyController.java. JWT request authentication is enforced by backend/src/main/java/com/akshansh/chessweb/filter/JwtAuthFilter.java under backend/src/main/java/com/akshansh/chessweb/config/SecurityConfig.java. STOMP connections have a separate JWT validation boundary in backend/src/main/java/com/akshansh/chessweb/config/WebSocketAuthInterceptor.java and broker setup in backend/src/main/java/com/akshansh/chessweb/config/WebSocketConfig.java.

Authoritative game lifecycle

backend/src/main/java/com/akshansh/chessweb/service/GameService.java coordinates game creation/joining, moves, draw/resign/end-state handling, and real-time synchronization. backend/src/main/java/com/akshansh/chessweb/service/MoveValidatorService.java applies chesslib-based server-side legality validation. Active runtime sessions are separated from durable records via backend/src/main/java/com/akshansh/chessweb/service/GameStore.java and backend/src/main/java/com/akshansh/chessweb/service/GamePersistenceService.java; scheduled clock/timeout processing resides in backend/src/main/java/com/akshansh/chessweb/service/SchedulerService.java.

Identity, persistence, and external services

backend/src/main/java/com/akshansh/chessweb/service/AuthService.java manages registration, verified login, JWT access tokens, and refresh-token rotation; verification email delivery uses Resend through backend/src/main/java/com/akshansh/chessweb/service/ResendEmailService.java. PostgreSQL is accessed with Spring Data JPA repositories, notably backend/src/main/java/com/akshansh/chessweb/repository/GameRepository.java and backend/src/main/java/com/akshansh/chessweb/repository/MoveRepository.java. Durable domain records include backend/src/main/java/com/akshansh/chessweb/model/entity/Game.java, backend/src/main/java/com/akshansh/chessweb/model/entity/MoveRecord.java, and backend/src/main/java/com/akshansh/chessweb/model/entity/User.java; Flyway initializes/evolves schema in backend/src/main/resources/db/migration/V1__init_schema.sql.

Runtime and deployment

Frontend requires Node.js and serves on port 3000 by default. Backend targets Java 21/Spring Boot with virtual threads, Maven, and a container definition at backend/Dockerfile; it runs on port 8080 by default. Required infrastructure is PostgreSQL plus Resend’s transactional-email API. Client API/WS URLs and backend datasource, JWT, CORS/frontend-origin, and Resend credentials are environment-configured.