# cotovsk1/chess-game architecture

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

- Interactive diagram: https://gitdiagram.com/cotovsk1/chess-game
- Repository: https://github.com/cotovsk1/chess-game

## Overview

Chess Game is a browser-based platform for bot and real-time multiplayer chess. Players use the web UI to authenticate, start or join a game, make moves, and review results; supporting capabilities include custom FEN starts, clocks, hints, chat, friends, and ratings. The FastAPI routers own the request and WebSocket actions, with shared game logic and in-memory state behind them and SQLite for persistent records. Edges reflect sampled calls or README-described behavior; unsampled details are not inferred.

Main entry points: [`backend/routers/game.py`](https://github.com/cotovsk1/chess-game/blob/master/backend/routers/game.py) (Bot game API), [`backend/database.py`](https://github.com/cotovsk1/chess-game/blob/master/backend/database.py) (DB sessions), [`backend/main.py`](https://github.com/cotovsk1/chess-game/blob/master/backend/main.py) (FastAPI app), [`backend/models.py`](https://github.com/cotovsk1/chess-game/blob/master/backend/models.py) (Persistent models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_frontend["Game UI"]
end

subgraph group_api["API and identity"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Accounts<br/>[auth.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_play["Chess gameplay"]
  node_gameapi["Bot game API<br/>[game.py]"]
  node_wsapi["Multiplayer sockets<br/>[websocket.py]"]
  node_logic["Chess engine logic<br/>[game_logic.py]"]
  node_state["Live game state<br/>[state_manager.py]"]
end

subgraph group_social["Social features"]
  node_chat["Chat API<br/>[chat.py]"]
  node_friends["Friend management<br/>[friends.py]"]
  node_elo["Rating calculation<br/>[utils.py]"]
end

subgraph group_storage["Persistence"]
  node_dbsession["DB sessions<br/>[database.py]"]
  node_models["Persistent models<br/>[models.py]"]
  node_sqlite[("SQLite database<br/>[chess_base.db]")]
end

node_player(("Player"))
node_stockfish["Stockfish"]

node_player -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_app
node_app -->|"registers"| node_gameapi
node_app -->|"registers"| node_wsapi
node_app -->|"registers"| node_auth
node_app -->|"registers"| node_chat
node_app -->|"registers"| node_friends
node_gameapi -->|"executes moves"| node_logic
node_gameapi -->|"stores games"| node_state
node_wsapi -->|"uses managers"| node_state
node_wsapi -->|"executes moves"| node_logic
node_logic -.->|"requests moves"| node_stockfish
node_auth -->|"gets sessions"| node_dbsession
node_auth -->|"queries players"| node_models
node_friends -->|"gets sessions"| node_dbsession
node_friends -->|"manages relations"| node_models
node_friends -->|"sends notices"| node_state
node_chat -->|"gets sessions"| node_dbsession
node_chat -->|"reads messages"| node_models
node_chat -->|"checks game"| node_state
node_gameapi -->|"gets sessions"| node_dbsession
node_gameapi -->|"records games"| node_models
node_gameapi -->|"updates ratings"| node_elo
node_wsapi -->|"opens sessions"| node_dbsession
node_wsapi -->|"records activity"| node_models
node_dbsession -->|"persists data"| node_sqlite
node_models -->|"uses base"| node_dbsession
node_gameapi -->|"validates requests"| node_schemas
node_auth -->|"shapes responses"| node_schemas
node_chat -->|"shapes responses"| node_schemas
node_friends -->|"shapes responses"| node_schemas

click node_frontend "https://github.com/cotovsk1/chess-game/tree/master/frontend"
click node_app "https://github.com/cotovsk1/chess-game/blob/master/backend/main.py"
click node_auth "https://github.com/cotovsk1/chess-game/blob/master/backend/routers/auth.py"
click node_schemas "https://github.com/cotovsk1/chess-game/blob/master/backend/schemas.py"
click node_gameapi "https://github.com/cotovsk1/chess-game/blob/master/backend/routers/game.py"
click node_wsapi "https://github.com/cotovsk1/chess-game/blob/master/backend/routers/websocket.py"
click node_logic "https://github.com/cotovsk1/chess-game/blob/master/backend/game_logic.py"
click node_state "https://github.com/cotovsk1/chess-game/blob/master/backend/state_manager.py"
click node_chat "https://github.com/cotovsk1/chess-game/blob/master/backend/routers/chat.py"
click node_friends "https://github.com/cotovsk1/chess-game/blob/master/backend/routers/friends.py"
click node_elo "https://github.com/cotovsk1/chess-game/blob/master/backend/utils.py"
click node_dbsession "https://github.com/cotovsk1/chess-game/blob/master/backend/database.py"
click node_models "https://github.com/cotovsk1/chess-game/blob/master/backend/models.py"
click node_sqlite "https://github.com/cotovsk1/chess-game/blob/master/chess_base.db"

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_frontend toneBlue
class node_app,node_auth,node_schemas toneAmber
class node_gameapi,node_wsapi,node_logic,node_state toneMint
class node_chat,node_friends,node_elo toneRose
class node_dbsession,node_models,node_sqlite,node_player,node_stockfish toneIndigo
```

## Components

### Web client

- [Game UI](https://github.com/cotovsk1/chess-game/tree/master/frontend): `frontend`

### API and identity

- [FastAPI app](https://github.com/cotovsk1/chess-game/blob/master/backend/main.py): `backend/main.py`
- [Accounts](https://github.com/cotovsk1/chess-game/blob/master/backend/routers/auth.py): `backend/routers/auth.py`
- [API schemas](https://github.com/cotovsk1/chess-game/blob/master/backend/schemas.py): `backend/schemas.py`

### Chess gameplay

- [Bot game API](https://github.com/cotovsk1/chess-game/blob/master/backend/routers/game.py): `backend/routers/game.py`
- [Multiplayer sockets](https://github.com/cotovsk1/chess-game/blob/master/backend/routers/websocket.py): `backend/routers/websocket.py`
- [Chess engine logic](https://github.com/cotovsk1/chess-game/blob/master/backend/game_logic.py): `backend/game_logic.py`
- [Live game state](https://github.com/cotovsk1/chess-game/blob/master/backend/state_manager.py): `backend/state_manager.py`

### Social features

- [Chat API](https://github.com/cotovsk1/chess-game/blob/master/backend/routers/chat.py): `backend/routers/chat.py`
- [Friend management](https://github.com/cotovsk1/chess-game/blob/master/backend/routers/friends.py): `backend/routers/friends.py`
- [Rating calculation](https://github.com/cotovsk1/chess-game/blob/master/backend/utils.py): `backend/utils.py`

### Persistence

- [DB sessions](https://github.com/cotovsk1/chess-game/blob/master/backend/database.py): `backend/database.py`
- [Persistent models](https://github.com/cotovsk1/chess-game/blob/master/backend/models.py): `backend/models.py`
- [SQLite database](https://github.com/cotovsk1/chess-game/blob/master/chess_base.db): `chess_base.db`

### Other components

- **Player**
- **Stockfish**

## Connections

- Player → Game UI: uses (evidence: `README.md`)
- Game UI → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → Bot game API: registers (evidence: `backend/main.py`)
- FastAPI app → Multiplayer sockets: registers (evidence: `backend/main.py`)
- FastAPI app → Accounts: registers (evidence: `backend/main.py`)
- FastAPI app → Chat API: registers (evidence: `backend/main.py`)
- FastAPI app → Friend management: registers (evidence: `backend/main.py`)
- Bot game API → Chess engine logic: executes moves (evidence: `backend/routers/game.py`)
- Bot game API → Live game state: stores games (evidence: `backend/routers/game.py`)
- Multiplayer sockets → Live game state: uses managers (evidence: `backend/routers/websocket.py`)
- Multiplayer sockets → Chess engine logic: executes moves (evidence: `backend/routers/websocket.py`)
- Chess engine logic → Stockfish: requests moves (evidence: `README.md`)
- Accounts → DB sessions: gets sessions (evidence: `backend/routers/auth.py`)
- Accounts → Persistent models: queries players (evidence: `backend/routers/auth.py`)
- Friend management → DB sessions: gets sessions (evidence: `backend/routers/friends.py`)
- Friend management → Persistent models: manages relations (evidence: `backend/routers/friends.py`)
- Friend management → Live game state: sends notices (evidence: `backend/routers/friends.py`)
- Chat API → DB sessions: gets sessions (evidence: `backend/routers/chat.py`)
- Chat API → Persistent models: reads messages (evidence: `backend/routers/chat.py`)
- Chat API → Live game state: checks game (evidence: `backend/routers/chat.py`)
- Bot game API → DB sessions: gets sessions (evidence: `backend/routers/game.py`)
- Bot game API → Persistent models: records games (evidence: `backend/routers/game.py`)
- Bot game API → Rating calculation: updates ratings (evidence: `backend/routers/game.py`)
- Multiplayer sockets → DB sessions: opens sessions (evidence: `backend/routers/websocket.py`)
- Multiplayer sockets → Persistent models: records activity (evidence: `backend/routers/websocket.py`)
- DB sessions → SQLite database: persists data (evidence: `backend/database.py`)
- Persistent models → DB sessions: uses base (evidence: `backend/models.py`)
- Bot game API → API schemas: validates requests (evidence: `backend/routers/game.py`)
- Accounts → API schemas: shapes responses (evidence: `backend/routers/auth.py`)
- Chat API → API schemas: shapes responses (evidence: `backend/routers/chat.py`)
- Friend management → API schemas: shapes responses (evidence: `backend/routers/friends.py`)
