# l1ghtweight/lightchess architecture

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

- Interactive diagram: https://gitdiagram.com/l1ghtweight/lightchess
- Repository: https://github.com/l1ghtweight/lightchess

## Overview

##### Main Components

A. Frontend Layer:
- React Application (TypeScript/JavaScript)
- Key Components:
- Game Components (Chessboard, Timer, GameInfo)
- Authentication Components (Login, Register, SignIn, SignUp)
- User Interface Components (Dashboard, Leaderboard, Profile)
- Real-time Components (Chat, Matchmaking)

B. Backend Layer:
- Express.js Server (TypeScript)
- Authentication System
- Game Logic Module
- WebSocket Server (Socket.io)

C. Database Layer:
- MariaDB with Sequelize ORM
- Key Models:
- User Model
- Games Model
- Federated User Model (for OAuth)

D. External Services:
- Google OAuth
- Email Service

##### Component Relationships

- Backend → Database: Database queries through Sequelize
- Backend → External Services: OAuth and email service connections

##### Specific Implementation Details

Architectural patterns:
- MVC Pattern in Backend (visible in controllers/models structure)
- Component-based architecture in Frontend
- Token-based authentication flow
- Real-time game state management

**┌─────────────────────────────────────────────┐**
- Client Layer (Browser)                      │
- ┌─────────────────┐    ┌────────────────┐ │
- React Frontend  │    │ Static Assets  │ │
- ┘    └────────────────┘ │
- ┘
- ↕ HTTP/WebSocket
**┌─────────────────────────────────────────────┐**
- Server Layer                                │
- ┌─────────────┐  ┌────────────┐  ┌──────┐ │
- Express API  │  │Socket.io   │  │Auth  │ │
- ┘  └────────────┘  └──────┘ │
- ┘
- ↕ Sequelize ORM
**┌─────────────────────────────────────────────┐**
- Data Layer                                  │
- ┌─────────────┐    ┌──────────────────┐   │
- MariaDB    │    │ External Services│   │
- ┘    └──────────────────┘   │
- ┘

##### Important Details to Highlight

- Authentication flow with JWT tokens
- Real-time game state management via Socket.io
- Database relationships between Users and Games
- Integration points with external services
- Static asset handling (sounds, images)
- API routes and controllers structure

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        FE[React Frontend]
        GC[Game Components]
        AC[Auth Components]
        UI[UI Components]
        RT[Real-time Components]
        SA[Static Assets]

        FE --> GC
        FE --> AC
        FE --> UI
        FE --> RT
        FE --> SA

        subgraph GameComponents
            CB[Chessboard]
            TM[Timer]
            GI[GameInfo]
        end

        subgraph AuthComponents
            LG[Login]
            RG[Register]
            SI[SignIn]
            SU[SignUp]
        end

        subgraph UIComponents
            DB[Dashboard]
            LB[Leaderboard]
            PF[Profile]
            UC[UserCard]
        end

        subgraph RealTimeComponents
            CH[Chat]
            MM[Matchmaking]
            QG[Quick Game]
        end
    end

    subgraph Server
        EX[Express API]
        WS[WebSocket Server]
        GL[Game Logic]
        EM[Email Service]
        TK[Token Management]
        UT[Utils]
        AC_BE[Auth Controller]
        TV[Token Verification]
    end

    subgraph Database
        DB_CONFIG[Database Config]
        UM[User Model]
        GM[Games Model]
        FUM[Federated User Model]
    end

    subgraph External
        GO[Google OAuth]
        EV[Email Verification]
    end

    Client <--> |HTTP/WS| Server
    Server --> Database
    Server --> External

    %% Click events for components
    click CB "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Chessboard.js"
    click TM "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Timer.js"
    click GI "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/GameInfo.js"
    click SA "https://github.com/L1ghtweight/lightchess/tree/main/frontend/src/components/static/sounds/"
    click LG "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Login.js"
    click RG "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Register.js"
    click SI "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/SignIn.js"
    click SU "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/SignUp.js"
    click DB "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Dashboard.js"
    click LB "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Leaderboard.js"
    click PF "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Profile.js"
    click UC "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/UserCard.js"
    click CH "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Chat.js"
    click MM "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Matchmaking.js"
    click QG "https://github.com/L1ghtweight/lightchess/blob/main/frontend/src/components/Quick_Game.js"
    click GL "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/modules/Games.ts"
    click EM "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/modules/SendEmail.ts"
    click TK "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/modules/Tokens.ts"
    click UT "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/modules/Utils.ts"
    click AC_BE "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/controllers/Auth/Auth.ts"
    click TV "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/middleware/VerifyToken.ts"
    click DB_CONFIG "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/config/Database.ts"
    click UM "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/models/UserModel.ts"
    click GM "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/models/GamesModel.ts"
    click FUM "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/models/FederatedUserModel.ts"
    click GO "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/routes/router-google.ts"
    click EV "https://github.com/L1ghtweight/lightchess/blob/main/backend/src/controllers/EmailVerification.ts"

    classDef frontend fill:#2374ab
    classDef backend fill:#2a9d8f
    classDef database fill:#e76f51
    classDef external fill:#95a5a6
    classDef realtime fill:#8338ec

    class FE,GC,AC,UI,RT,SA,CB,TM,GI,LG,RG,SI,SU,DB,LB,PF,UC,CH,MM,QG frontend
    class EX,GL,EM,TK,UT,AC_BE,TV backend
    class DB_CONFIG,UM,GM,FUM database
    class GO,EV external
    class WS realtime
```
