# surajbkale/chessverse architecture

> Architecture diagram of the GitHub repository surajbkale/chessverse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/surajbkale/chessverse
- Repository: https://github.com/surajbkale/chessverse

## Overview

ChessVerse is a real-time multiplayer chess platform. A player enters through the web app, authenticates or plays as a guest, starts random matchmaking or joins a shared game, then plays and reviews moves over WebSockets. The backend handles login and sessions; the WebSocket service coordinates matching, game state, persistence, and reconnectable room delivery. The README also documents profile/statistics, themes, board controls, sharing, and game-result features. Some feature components are unsampled, so their placement follows documented capabilities; edges are limited to visible calls or README statements.

Main entry points: [`apps/frontend/src/screens/Game.tsx`](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/screens/Game.tsx) (Game screen), [`apps/frontend/src/App.tsx`](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/App.tsx) (App routes), [`apps/backend/src/index.ts`](https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/index.ts) (API server), [`apps/ws/src/GameManager.ts`](https://github.com/surajbkale/chessverse/blob/main/apps/ws/src/GameManager.ts) (Match and room manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["App routes<br/>[App.tsx]"]
  node_landing["Landing and match<br/>[Landing.tsx]"]
  node_login["Login screen<br/>[Login.tsx]"]
  node_gameui["Game screen<br/>[Game.tsx]"]
  node_board["Chess board<br/>[ChessBoard.tsx]"]
  node_history["Move history<br/>[MovesTable.tsx]"]
  node_themes["Themes<br/>[themes.tsx]"]
  node_socket_hook["Socket connection<br/>[useSocket.ts]"]
end

subgraph group_identity["Identity and API"]
  node_backend["API server<br/>[index.ts]"]
  node_auth["Auth routes<br/>[auth.ts]"]
  node_passport["OAuth strategies<br/>[passport.ts]"]
  node_api_v1["V1 API routes<br/>[v1.ts]"]
end

subgraph group_realtime["Realtime gameplay"]
  node_manager["Match and room manager<br/>[GameManager.ts]"]
  node_game["Game state<br/>[Game.ts]"]
  node_socket_manager["Socket rooms<br/>[SocketManager.ts]"]
  node_redis[("Redis")]
end

subgraph group_shared["Shared state"]
  node_database[("PostgreSQL")]
  node_store["Shared game and user state<br/>[user.ts]"]
end

node_player(("Player"))
node_oauth(("Google / GitHub"))

node_player -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_landing
node_webapp -->|"routes to"| node_login
node_webapp -->|"routes to"| node_gameui
node_webapp -->|"routes to"| node_themes
node_player -->|"authenticates"| node_login
node_login -.->|"requests auth"| node_backend
node_oauth -->|"authenticates"| node_auth
node_backend -->|"mounts"| node_auth
node_backend -->|"initializes"| node_passport
node_backend -->|"mounts"| node_api_v1
node_auth -->|"reads and writes users"| node_database
node_auth -->|"authenticates with"| node_passport
node_landing -->|"starts play"| node_gameui
node_gameui -->|"opens connection"| node_socket_hook
node_socket_hook -->|"reads user token"| node_store
node_socket_hook -.->|"sends game messages"| node_manager
node_gameui -->|"renders"| node_board
node_gameui -->|"renders"| node_history
node_board -->|"uses board state"| node_store
node_board -->|"accepts moves"| node_player
node_manager -->|"creates and dispatches"| node_game
node_manager -->|"loads games"| node_database
node_manager -->|"claims pending match"| node_redis
node_game -->|"persists moves and results"| node_database
node_game -->|"broadcasts results"| node_socket_manager
node_socket_manager -->|"publishes and subscribes"| node_redis
node_socket_manager -->|"delivers room updates"| node_player
node_game -->|"runs timed chess"| node_player
node_player -->|"reviews moves"| node_gameui

click node_webapp "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/App.tsx"
click node_landing "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/screens/Landing.tsx"
click node_login "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/screens/Login.tsx"
click node_gameui "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/screens/Game.tsx"
click node_board "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/components/ChessBoard.tsx"
click node_history "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/components/MovesTable.tsx"
click node_themes "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/components/themes.tsx"
click node_socket_hook "https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/hooks/useSocket.ts"
click node_backend "https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/index.ts"
click node_auth "https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/router/auth.ts"
click node_passport "https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/passport.ts"
click node_api_v1 "https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/router/v1.ts"
click node_manager "https://github.com/surajbkale/chessverse/blob/main/apps/ws/src/GameManager.ts"
click node_game "https://github.com/surajbkale/chessverse/blob/main/apps/ws/src/Game.ts"
click node_socket_manager "https://github.com/surajbkale/chessverse/blob/main/apps/ws/src/SocketManager.ts"
click node_store "https://github.com/surajbkale/chessverse/blob/main/packages/store/src/atoms/user.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_landing,node_login,node_gameui,node_board,node_history,node_themes,node_socket_hook toneBlue
class node_backend,node_auth,node_passport,node_api_v1 toneAmber
class node_manager,node_game,node_socket_manager,node_redis toneMint
class node_database,node_store toneRose
class node_player,node_oauth toneIndigo
```

## Components

### Web client

- [App routes](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/App.tsx): `apps/frontend/src/App.tsx`
- [Landing and match](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/screens/Landing.tsx): `apps/frontend/src/screens/Landing.tsx`
- [Login screen](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/screens/Login.tsx): `apps/frontend/src/screens/Login.tsx`
- [Game screen](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/screens/Game.tsx): `apps/frontend/src/screens/Game.tsx`
- [Chess board](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/components/ChessBoard.tsx): `apps/frontend/src/components/ChessBoard.tsx`
- [Move history](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/components/MovesTable.tsx): `apps/frontend/src/components/MovesTable.tsx`
- [Themes](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/components/themes.tsx): `apps/frontend/src/components/themes.tsx`
- [Socket connection](https://github.com/surajbkale/chessverse/blob/main/apps/frontend/src/hooks/useSocket.ts): `apps/frontend/src/hooks/useSocket.ts`

### Identity and API

- [API server](https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/index.ts): `apps/backend/src/index.ts`
- [Auth routes](https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/router/auth.ts): `apps/backend/src/router/auth.ts`
- [OAuth strategies](https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/passport.ts): `apps/backend/src/passport.ts`
- [V1 API routes](https://github.com/surajbkale/chessverse/blob/main/apps/backend/src/router/v1.ts): `apps/backend/src/router/v1.ts`

### Realtime gameplay

- [Match and room manager](https://github.com/surajbkale/chessverse/blob/main/apps/ws/src/GameManager.ts): `apps/ws/src/GameManager.ts`
- [Game state](https://github.com/surajbkale/chessverse/blob/main/apps/ws/src/Game.ts): `apps/ws/src/Game.ts`
- [Socket rooms](https://github.com/surajbkale/chessverse/blob/main/apps/ws/src/SocketManager.ts): `apps/ws/src/SocketManager.ts`
- **Redis**

### Shared state

- **PostgreSQL**
- [Shared game and user state](https://github.com/surajbkale/chessverse/blob/main/packages/store/src/atoms/user.ts): `packages/store/src/atoms/user.ts`

### Other components

- **Player**
- **Google / GitHub**

## Connections

- Player → App routes: uses (evidence: `README.md`)
- App routes → Landing and match: routes to (evidence: `apps/frontend/src/App.tsx`)
- App routes → Login screen: routes to (evidence: `apps/frontend/src/App.tsx`)
- App routes → Game screen: routes to (evidence: `apps/frontend/src/App.tsx`)
- App routes → Themes: routes to (evidence: `apps/frontend/src/App.tsx`)
- Player → Login screen: authenticates (evidence: `README.md`)
- Login screen → API server: requests auth
- Google / GitHub → Auth routes: authenticates (evidence: `README.md`)
- API server → Auth routes: mounts (evidence: `apps/backend/src/index.ts`)
- API server → OAuth strategies: initializes (evidence: `apps/backend/src/index.ts`)
- API server → V1 API routes: mounts (evidence: `apps/backend/src/index.ts`)
- Auth routes → PostgreSQL: reads and writes users (evidence: `apps/backend/src/router/auth.ts`)
- Auth routes → OAuth strategies: authenticates with (evidence: `apps/backend/src/router/auth.ts`)
- Landing and match → Game screen: starts play (evidence: `README.md`)
- Game screen → Socket connection: opens connection (evidence: `apps/frontend/src/screens/Game.tsx`)
- Socket connection → Shared game and user state: reads user token (evidence: `apps/frontend/src/hooks/useSocket.ts`)
- Socket connection → Match and room manager: sends game messages
- Game screen → Chess board: renders (evidence: `apps/frontend/src/screens/Game.tsx`)
- Game screen → Move history: renders (evidence: `apps/frontend/src/screens/Game.tsx`)
- Chess board → Shared game and user state: uses board state (evidence: `apps/frontend/src/components/ChessBoard.tsx`)
- Chess board → Player: accepts moves (evidence: `README.md`)
- Match and room manager → Game state: creates and dispatches (evidence: `apps/ws/src/GameManager.ts`)
- Match and room manager → PostgreSQL: loads games (evidence: `apps/ws/src/GameManager.ts`)
- Match and room manager → Redis: claims pending match (evidence: `apps/ws/src/GameManager.ts`)
- Game state → PostgreSQL: persists moves and results (evidence: `apps/ws/src/Game.ts`)
- Game state → Socket rooms: broadcasts results (evidence: `apps/ws/src/Game.ts`)
- Socket rooms → Redis: publishes and subscribes (evidence: `apps/ws/src/SocketManager.ts`)
- Socket rooms → Player: delivers room updates (evidence: `apps/ws/src/SocketManager.ts`)
- Game state → Player: runs timed chess (evidence: `README.md`)
- Player → Game screen: reviews moves (evidence: `README.md`)
