# recepsalih03/game-center architecture

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

- Interactive diagram: https://gitdiagram.com/recepsalih03/game-center
- Repository: https://github.com/recepsalih03/game-center

## Overview

##### Project type and purpose
- This is a full-stack, real-time, multiplayer gaming platform built as a modular monorepo (Lerna + NPM workspaces).
- Purpose: allow users to authenticate, join or create lobbies, play a synchronized Tombala game in real time, and receive notifications.

##### File structure
- Top-level “packages/” contains three key sub-packages:
- client (React/TS UI)
- server (Node/Express/TS REST + WebSocket backend)
- config (shared configuration, e.g. user lists)
- There’s also a “game-tombala” package holding core game logic used by the server.
- Client folder: public assets, React components, pages, contexts (Auth, Socket, Theme), hooks, services (API & socket wrappers).
- Server folder: Express app entrypoint, REST routes (auth, games, lobbies, public/protected), game-handlers for game logic, in-memory store, middleware (auth, error handler, logger), utils (JWT, hashing).

##### Inspect README for architecture insights
- JWT-based authentication, Socket.IO for real-time lobby & game sync.
- Modular game architecture: game-tombala plug-in.
- Two development servers (client:3000, server:4000) with proxying for CORS.

##### Main components and interactions
a. Components
- Frontend (React SPA)
– UI Layers: Pages, Components, Context Providers (AuthContext, SocketContext, ThemeContext)
– Services: Axios HTTP client, Socket.IO client
- Backend (Express API + WebSocket)
– HTTP REST endpoints: /auth, /games, /lobbies (public/protected)
– WebSocket channels (namespaces or events) for lobbies & game events
– Game Logic Engine (game-tombala handler)
– In-Memory Store for lobbies, active games, user sessions
– Middleware: JWT auth, logging, error handling
- Shared Config (users, settings)
- External concerns
– JWT issuer/validator (jsonwebtoken)
– Browser (sound & toast notifications via react-toastify)
– Developer machines running npm run dev

b. Relationships & data flow
1. User opens browser → React client served from dev server or build.
2. Client → HTTP POST /auth/login → Server (JWT issued).
3. Client stores JWT and attaches it to subsequent HTTP headers or Socket.IO handshake.
4. Client fetches game and lobby lists via REST.
5. Client connects to Socket.IO channel, authenticates via JWT on connect.
6. Real-time lobby events (join/leave/invite/start game) flow bi-directionally over WebSocket.
8. On game end, server broadcasts result; clients display GameOverDialog.

c. Architectural patterns & principles
- Monorepo modularization (shared config, game logic plug-in)
- Separation of concerns (UI vs API vs real-time engine)
- Context-driven state management in React
- Middleware pipeline for authentication, logging, error handling
- Single in-memory store (no external DB; extendable to Redis or SQL)
- Event-driven design via Socket.IO

d. Key technologies to call out
- React 18 + TypeScript + MUI v5 + React Router v6
- Axios + React-Toastify + Socket.IO client
- Node.js + Express.js + TypeScript + Socket.IO server
- jsonwebtoken for JWT, bcrypt or custom hash util
- Lerna + NPM workspaces for monorepo management

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Frontend Layer
  subgraph "Frontend (React SPA)"
    direction TB
    Browser["Browser (User)"]:::external
    HomePage["HomePage"]:::frontend
    LoginPage["LoginPage"]:::frontend
    GameDetailPage["GameDetailPage"]:::frontend
    GamePlayPage["GamePlayPage"]:::frontend
    AuthContext["AuthContext"]:::frontend
    SocketContext["SocketContext"]:::frontend
    ThemeContext["ThemeContext"]:::frontend
    AxiosClient["Axios HTTP Client"]:::frontend
    SocketClient["Socket.IO Client"]:::websocket
    AuthService["AuthService"]:::frontend
    GamesService["GamesService"]:::frontend
    LobbiesService["LobbiesService"]:::frontend
    GameOverDialog["GameOverDialog"]:::frontend
    LobbyList["LobbyList"]:::frontend
    LobbyForm["LobbyForm"]:::frontend
    LobbySidebar["LobbySidebar"]:::frontend
    InviteNotification["InviteNotification"]:::frontend
    InvitePlayerDialog["InvitePlayerDialog"]:::frontend
  end

  %% Backend Layer
  subgraph "Backend (Express API + WebSocket)"
    direction TB
    ExpressApp["Express App Entrypoint"]:::backend
    subgraph "Middleware Pipeline"
      AuthMiddleware["JWT Auth Middleware"]:::backend
      LoggerMiddleware["Request Logger"]:::backend
      ErrorMiddleware["Error Handler"]:::backend
    end
    subgraph "REST Routes"
      AuthRoutes["/auth routes"]:::backend
      GamesRoutes["/games routes"]:::backend
      LobbiesRoutes["/lobbies routes"]:::backend
      PublicRoutes["Public Route Group"]:::backend
      ProtectedRoutes["Protected Route Group"]:::backend
    end
    subgraph "WebSocket Layer"
      LobbyNamespace["Lobby Namespace"]:::websocket
      GameNamespace["Game Namespace"]:::websocket
    end
    GameHandler["Game-Tombala Handler"]:::backend
    InMemoryStore["In-Memory Store\n(lobbies, games, sessions)"]:::datastore
    subgraph "Utils & Config"
      JWTUtil["JWT Util"]:::backend
      HashUtil["Hash Util"]:::backend
      SharedConfig["Shared Config\n(users, settings)"]:::datastore
    end
  end

  %% External
  JWTLib["jsonwebtoken (External)"]:::external
  Developer["Developer Machine\nnpm run dev"]:::external

  %% Flows
  Browser -->|"opens SPA"| HomePage
  Browser --> LoginPage
  LoginPage --> AuthService
  AuthService -->|"POST /auth/login"| ExpressApp
  ExpressApp --> AuthMiddleware --> AuthRoutes
  AuthRoutes --> JWTUtil
  AuthRoutes --> SharedConfig
  ExpressApp --> LoggerMiddleware --> GamesRoutes
  ExpressApp --> LoggerMiddleware --> LobbiesRoutes
  GamesRoutes --> GameHandler
  LobbiesRoutes --> InMemoryStore
  ExpressApp --> ErrorMiddleware

  HomePage --> GamesService
  HomePage --> LobbiesService
  GamesService -->|"GET /games"| ExpressApp
  LobbiesService -->|"GET /lobbies"| ExpressApp

  Browser --> SocketClient
  SocketClient -->|"connect w/ JWT"| LobbyNamespace
  SocketClient -->|"connect w/ JWT"| GameNamespace
  LobbyNamespace --> InMemoryStore
  GameNamespace --> InMemoryStore
  GameNamespace --> GameHandler
  GameHandler --> InMemoryStore
  GameHandler --> LobbyNamespace
  GameHandler --> GameNamespace

  AuthContext --> AuthService
  SocketContext --> SocketClient
  ThemeContext --> HomePage

  HomePage --> LobbyList
  HomePage --> LobbyForm
  HomePage --> LobbySidebar
  LobbySidebar --> InviteNotification
  LobbySidebar --> InvitePlayerDialog
  GamePlayPage --> GameOverDialog

  Developer --> Browser
  Developer --> ExpressApp

  %% Click events
  click AuthContext "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/contexts/AuthContext.tsx"
  click SocketContext "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/contexts/SocketContext.tsx"
  click ThemeContext "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/contexts/ThemeContext.tsx"
  click AxiosClient "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/api/axios.ts"
  click AuthService "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/services/authService.ts"
  click GamesService "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/services/gamesService.ts"
  click LobbiesService "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/services/lobbiesService.ts"
  click HomePage "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/pages/HomePage.tsx"
  click LoginPage "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/pages/LoginPage.tsx"
  click GameDetailPage "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/pages/GameDetailPage.tsx"
  click GamePlayPage "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/pages/GamePlayPage.tsx"
  click GameOverDialog "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/components/GameOverDialog.tsx"
  click LobbyList "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/components/LobbyList.tsx"
  click LobbyForm "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/components/LobbyForm.tsx"
  click LobbySidebar "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/components/LobbySidebar.tsx"
  click InviteNotification "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/components/InviteNotification.tsx"
  click InvitePlayerDialog "https://github.com/recepsalih03/game-center/blob/main/packages/client/src/components/InvitePlayerDialog.tsx"
  click ExpressApp "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/index.ts"
  click AuthMiddleware "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/middleware/auth.ts"
  click LoggerMiddleware "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/middleware/logger.ts"
  click ErrorMiddleware "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/middleware/errorHandler.ts"
  click AuthRoutes "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/routes/auth.ts"
  click GamesRoutes "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/routes/games.ts"
  click LobbiesRoutes "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/routes/lobbies.ts"
  click PublicRoutes "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/routes/public.ts"
  click ProtectedRoutes "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/routes/protected.ts"
  click InMemoryStore "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/data/inMemoryStore.ts"
  click GameHandler "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/game-handlers/tombala.handler.ts"
  click HashUtil "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/utils/hash.ts"
  click JWTUtil "https://github.com/recepsalih03/game-center/blob/main/packages/server/src/utils/jwt.ts"
  click SharedConfig "https://github.com/recepsalih03/game-center/blob/main/packages/config/users.ts"
  click GameLogicPlugin "https://github.com/recepsalih03/game-center/tree/main/packages/game-tombala"

  %% Styles
  classDef frontend fill:#add8e6,stroke:#333,stroke-width:1px
  classDef backend fill:#98fb98,stroke:#333,stroke-width:1px
  classDef websocket fill:#ffa500,stroke:#333,stroke-width:1px
  classDef datastore fill:#d3d3d3,stroke:#333,stroke-width:1px
  classDef external fill:#f0e68c,stroke:#333,stroke-width:1px
```
