# lokesh-reddy18/chess-master architecture

> Architecture diagram of the GitHub repository lokesh-reddy18/chess-master, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lokesh-reddy18/chess-master
- Repository: https://github.com/lokesh-reddy18/chess-master

## Overview

##### Project Type & Purpose
- Chess Master is a full-stack web application for playing chess: local, global (real-time multiplayer), AI (Stockfish), and puzzles.
- It consists of a React/Vite/Tailwind frontend, a Node.js/Express backend, real-time via Socket.io, MongoDB Atlas storage, JWT auth, and the Stockfish engine.

##### Main Components
a. Frontend Client
- React app (Vite)
- UI Components (e.g., Game board, Navbar, Modals, Puzzles)
- State Management (Redux store via authSlice.js + store.js)
- SocketManager (real-time events)
- HTTP client for REST calls (auth-utils.js)
b. Backend Server
- Express.js HTTP API (userRoutes, profileRoutes)
- Socket.io server for real-time gameplay and matchmaking
- MVC layers:
- Controllers (UserController)
- Services (auth logic)
- Models (Mongoose userModel)
- Middlewares (JWT auth)
- Config & DB connection (connect.js, db.js)
c. Database
- MongoDB Atlas (users, profiles, game history)
d. External Services
- Stockfish chess engine (invoked for AI mode)
- Optionally, third-party hosting (Vercel/Render)

##### Component Interactions
- User opens React UI → makes HTTP requests to Express API for signup/login (JWT)
- On successful auth, client stores JWT and connects via Socket.io
- Socket.io channels handle:
- Global match queue (matchmaking)
- Real-time move events (broadcast between peers)
- Game over notifications
- For AI games, backend spawns Stockfish process or communicates via a Stockfish service
- Backend persists game results / profiles in MongoDB

##### Architectural Patterns & Design Principles
- Separation of concerns:
- Frontend vs Backend
- MVC pattern in backend
- Flux/Redux in frontend
- Layered architecture: API layer, business‐logic layer, data layer
- Event-driven design for real-time gameplay (Socket.io)
- Security: JWT authentication middleware
- Extensibility: services folder encapsulates auth, chess‐engine logic

## Diagram (Mermaid)

```mermaid
flowchart LR
    subgraph "Frontend Client" 
        direction TB
        REACT["React App\n(frontend/)"]:::frontend
        UI["UI Components\n(components/)"]:::frontend
        STORE["Redux Store\n(store/)"]:::frontend
        FE_SOCKET["SocketManager\n(SocketManager.js)"]:::frontend
        FE_HTTP["HTTP Client\n(auth-utils.js)"]:::frontend
    end

    subgraph "Backend Server"
        direction TB
        HTTP_API["Express HTTP API\n(routes/)"]:::backend
        SOCKET["Socket.io Server\n(server.js)"]:::backend
        subgraph "MVC Layers"
            CTRL["UserController\n(UserController.js)"]:::backend
            SRVC["Auth Service\n(auth.js)"]:::backend
            MODEL["User Model\n(userModel.js)"]:::backend
            MW["JWT Middleware\n(auth.js)"]:::backend
        end
        CFG["Config & DB Connection\n(connect.js, db.js)"]:::backend
    end

    subgraph "Persistence & External"
        direction TB
        DB["MongoDB Atlas"]:::db
        STOCK["Stockfish Engine"]:::external
    end

    %% Connections
    FE_HTTP -->|"HTTP (REST)"| HTTP_API
    HTTP_API -->|"HTTP Response"| FE_HTTP
    FE_SOCKET -->|"WS (emit/listen)"| SOCKET
    SOCKET -->|"WS (emit/listen)"| FE_SOCKET
    HTTP_API -->|"DB Query"| DB
    HTTP_API -->|"Engine Call"| STOCK

    %% Click Events
    click REACT "https://github.com/lokesh-reddy18/chess-master/tree/main/frontend/"
    click UI "https://github.com/lokesh-reddy18/chess-master/tree/main/frontend/src/components/"
    click STORE "https://github.com/lokesh-reddy18/chess-master/tree/main/frontend/src/store/"
    click FE_SOCKET "https://github.com/lokesh-reddy18/chess-master/blob/main/frontend/src/utils/SocketManager.js"
    click FE_HTTP "https://github.com/lokesh-reddy18/chess-master/blob/main/frontend/src/utils/auth-utils.js"
    click HTTP_API "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/routes/userRoutes.js"
    click SOCKET "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/server.js"
    click CFG "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/config/connect.js"
    click CFG "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/db.js"
    click CTRL "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/controllers/UserController.js"
    click SRVC "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/services/auth.js"
    click MODEL "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/models/userModel.js"
    click MW "https://github.com/lokesh-reddy18/chess-master/blob/main/backend/middlewares/auth.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#4285F4,stroke-width:1px
    classDef backend fill:#D0FFD8,stroke:#34A853,stroke-width:1px
    classDef db fill:#FFE3B3,stroke:#FBBC05,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#9AA0A6,stroke-width:1px

    %% Edge Styles
    linkStyle 2,3 stroke:#A020F0,stroke-dasharray:5,5
```
