# vanhphan292/chess_game architecture

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

- Interactive diagram: https://gitdiagram.com/vanhphan292/chess_game
- Repository: https://github.com/vanhphan292/chess_game

## Overview

##### Project Type and Purpose
- This is a full‐stack, real‐time web application for playing secure online chess matches.
- Frontend: React.js (SPA) served from Firebase Hosting.
- Backend: Node.js + Express with MongoDB (Mongoose), real‐time via Socket.IO, JWT‐based auth, Google reCAPTCHA, custom SSL certs.

##### File Structure
- Top-level directories:
- chess_frontend – React app (public assets, components, pages, context, hooks, services, styles)
- chess_backend – Express server (server.js, src/config, controllers, models, routes, middleware, services, socket, utils)
- The backend follows a layered MVC pattern:
- config (DB connection)
- routes → controllers → services → models
- Real‐time socket logic in src/socket/gameSocket.js.
- Security concerns addressed via middleware (auth, captcha, input validation, error handling).
- Deployment artifacts/configs: Firebase (firebase.json, .firebaserc), Render (implicit via certs folder).

##### Key Insights from README
- Real‐time multiplayer with Socket.IO.
- Security: JWT, bcrypt, Google reCAPTCHA, custom HTTPS.
- Persistent storage in MongoDB.
- Hosted: Frontend on Firebase, backend on Render.

##### Main Components
a. Client (Browser)
– React SPA (served by Firebase Hosting)
– Components/pages for UI, AuthContext, useChess hook, API/socket services
b. Frontend Hosting
– Firebase Hosting (serves static build)
c. Backend Application
– HTTPS Server (Express + custom SSL)
– REST API layer (auth, user, game routes)
– WebSocket (Socket.IO) for real‐time events
– Middleware (JWT validation, reCAPTCHA, input sanitization, DoS mitigation, error handler)
– Controllers → Services → Models (Mongoose)
d. Database
– MongoDB (hosted on Atlas or managed service)
e. External Services
– Google reCAPTCHA API
– JWT issuer/validator (internal)
f. Deployment Platforms
– Render (backend)
– Firebase (frontend)

##### Relationships and Data Flows
- HTTP(S) flow:
1) Browser → Firebase Hosting → static React → user actions → API calls over HTTPS → Express routes
2) Express middleware chain (auth, captcha, validation) → controllers → services → MongoDB → response
- WebSocket flow:
1) Browser Socket.IO client (token in handshake) → Express/Socket.IO server
2) gameSocket logic triggers service calls → updates DB → emits game state back to peers
- External calls:
– reCAPTCHA validation: backend → Google reCAPTCHA API
– Password reset emails/workflow (if applicable)

##### Architectural Patterns & Design Principles
- Layered MVC (Routes → Controllers → Services → Models)
- Modularized middleware for cross‐cutting concerns (auth, security, logging)
- Component‐based React + Context API + custom hooks for state management
- Real‐time event‐driven via Socket.IO
- Secure-by-design: HTTPS, JWT, input validation, rate limiting

##### Essential Details
- Don’t oversimplify: show both REST and WebSocket paths.
- That all traffic is over HTTPS (self‐signed certs) and authenticated via JWT.
- Call out the real‐time game loop: client emits “move” → backend validates via gameAdapter → updates DB → broadcasts new board state.
- Account recovery flow: user → password reset endpoint → email → secure token → reset form.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Lane
    subgraph "Frontend Layer" 
        direction TB
        FB_HOST["Firebase Hosting"]:::infra
        REACT_SPA["React SPA"]:::frontend
        subgraph "Firebase Config" 
            direction TB
            FB_JSON["firebase.json"]:::config
            FB_RC[".firebaserc"]:::config
        end
        subgraph "React Entry & App"
            direction TB
            ENTRY["src/index.js"]:::frontend
            APP["src/App.jsx"]:::frontend
        end
        subgraph "UI Components" 
            direction TB
            Board["Board.jsx"]:::frontend
            BoardSq["BoardSquare.jsx"]:::frontend
            Controls["GameControls.jsx"]:::frontend
            History["MoveHistory.jsx"]:::frontend
            Spinner["Spinner.jsx"]:::frontend
        end
        subgraph "Pages"
            direction TB
            Home["Home.jsx"]:::frontend
            Lobby["Lobby.jsx"]:::frontend
            Play["Play.jsx"]:::frontend
            SignIn["SignIn.jsx"]:::frontend
            SignUp["SignUp.jsx"]:::frontend
            PWRec["PWRec.jsx"]:::frontend
            ResetPW["ResetPW.jsx"]:::frontend
        end
        subgraph "Context & Hooks"
            direction TB
            AuthCtx["AuthContext.jsx"]:::frontend
            UseChess["useChess.js"]:::frontend
        end
        subgraph "Services & Utils"
            direction TB
            API_SRV["api.js"]:::frontend
            SOCKET_SRV["socket.js"]:::frontend
            SANITIZE["inputSanitize.js"]:::frontend
            STORAGE["storage.js"]:::frontend
        end
    end

    %% Backend Lane
    subgraph "Backend Layer"
        direction TB
        EXPRESS["Express API Server\n(server.js)"]:::backend
        subgraph "SSL Certificates"
            direction TB
            Certs["certs/"]:::config
        end
        subgraph "Middleware"
            direction TB
            JWT["auth.js"]:::backend
            CAPTCHA["captchaValidator.js"]:::backend
            USERVAL["userValidator.js"]:::backend
            ERRH["errorHandler.js"]:::backend
        end
        subgraph "MVC Layer"
            direction TB
            subgraph "Routes"
                direction TB
                AuthR["auth.js"]:::backend
                UserR["userRoutes.js"]:::backend
                GameR["game.js"]:::backend
            end
            subgraph "Controllers"
                direction TB
                UserC["userController.js"]:::backend
                GameC["gameController.js"]:::backend
            end
            subgraph "Services"
                direction TB
                GameS["GameService.js"]:::backend
            end
            subgraph "Models"
                direction TB
                UserM["user.js"]:::db
                GameM["Game.js"]:::db
            end
        end
        subgraph "WebSocket (Socket.IO)"
            direction TB
            SocketIO["gameSocket.js"]:::backend
        end
        subgraph "Utilities"
            direction TB
            Adapter["gameAdapter.js"]:::backend
            Logger["logger.js"]:::backend
        end
    end

    %% Database and External
    DB["MongoDB"]:::database
    Recaptcha["Google reCAPTCHA"]:::external

    %% Connections
    REACT_SPA -->|"serves static files"| FB_HOST
    FB_HOST -->|"delivers SPA"| REACT_SPA

    REACT_SPA -->|"HTTPS REST calls"| EXPRESS
    EXPRESS -->|"JWT Auth→Captcha→Validation"| JWT & CAPTCHA & USERVAL & ERRH
    JWT & CAPTCHA & USERVAL & ERRH --> AuthR & UserR & GameR
    AuthR --> UserC
    UserR --> UserC
    GameR --> GameC

    UserC --> GameS
    GameC --> GameS
    GameS --> UserM & GameM
    GameS --> DB
    AuthR -->|"password reset flow"| ERRH

    REACT_SPA -.->|"WebSocket handshake (token)"| SocketIO
    SocketIO --> Adapter
    Adapter --> GameS
    SocketIO -->|"emit events"| REACT_SPA

    EXPRESS --> DB
    EXPRESS --> Recaptcha
    ExpressRecap[.]:::invisible

    %% Class Definitions
    classDef frontend fill:#cce5ff,stroke:#4a90e2,color:#000;
    classDef backend fill:#e6ffe6,stroke:#2ecc71,color:#000;
    classDef database fill:#ffe6cc,stroke:#e67e22,color:#000;
    classDef external fill:#f0e6ff,stroke:#8e44ad,color:#000;
    classDef infra fill:#e8f1f8,stroke:#3498db,color:#000;
    classDef config fill:#f5f5f5,stroke:#7f8c8d,color:#000;
    classDef invisible fill:none,stroke:none;

    %% Click Events
    click REACT_SPA "https://github.com/vanhphan292/chess_game/tree/main/chess_frontend/"
    click FB_JSON "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/firebase.json"
    click FB_RC "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/.firebaserc"
    click ENTRY "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/index.js"
    click APP "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/App.jsx"
    click Board "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/components/Board.jsx"
    click BoardSq "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/components/BoardSquare.jsx"
    click Controls "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/components/GameControls.jsx"
    click History "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/components/MoveHistory.jsx"
    click Spinner "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/components/Spinner.jsx"
    click Home "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/pages/Home.jsx"
    click Lobby "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/pages/Lobby.jsx"
    click Play "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/pages/Play.jsx"
    click SignIn "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/pages/SignIn.jsx"
    click SignUp "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/pages/SignUp.jsx"
    click PWRec "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/pages/PWRec.jsx"
    click ResetPW "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/pages/ResetPW.jsx"
    click AuthCtx "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/context/AuthContext.jsx"
    click UseChess "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/hooks/useChess.js"
    click API_SRV "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/services/api.js"
    click SOCKET_SRV "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/services/socket.js"
    click SANITIZE "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/components/inputSanitize.js"
    click STORAGE "https://github.com/vanhphan292/chess_game/blob/main/chess_frontend/src/utils/storage.js"

    click EXPRESS "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/server.js"
    click Certs "https://github.com/vanhphan292/chess_game/tree/main/chess_backend/certs/"
    click JWT "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/middleware/auth.js"
    click CAPTCHA "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/middleware/captchaValidator.js"
    click USERVAL "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/middleware/userValidator.js"
    click ERRH "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/middleware/errorHandler.js"
    click AuthR "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/routes/auth.js"
    click UserR "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/routes/userRoutes.js"
    click GameR "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/routes/game.js"
    click UserC "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/controllers/userController.js"
    click GameC "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/controllers/gameController.js"
    click GameS "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/services/GameService.js"
    click UserM "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/models/user.js"
    click GameM "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/models/Game.js"
    click SocketIO "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/socket/gameSocket.js"
    click Adapter "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/utils/gameAdapter.js"
    click Logger "https://github.com/vanhphan292/chess_game/blob/main/chess_backend/src/utils/logger.js"
```
