# haidarmahdi099/online-chess-platform architecture

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

- Interactive diagram: https://gitdiagram.com/haidarmahdi099/online-chess-platform
- Repository: https://github.com/haidarmahdi099/online-chess-platform

## Overview

ChessPlatform is an online chess product: players authenticate, find or create games, play with authoritative server-side rules and live updates, then use puzzles, ratings, tournaments, profiles, and position analysis. The graph preserves those documented capabilities and distinguishes synchronous APIs from asynchronous event work. Source excerpts show several controller-to-service calls and the Stockfish engine integration; many subsystem internals and cross-service event links are documented only at README level, so those links are dashed where implementation wiring was not sampled.

Main entry points: [`backend/src/Gateway/Gateway/Program.cs`](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Gateway/Gateway/Program.cs) (YARP gateway), [`frontend/src/routes/index.tsx`](https://github.com/haidarmahdi099/online-chess-platform/blob/main/frontend/src/routes/index.tsx) (Chess web app), [`backend/src/Services/Game/Game.Api/Controllers/GamesController.cs`](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Api/Controllers/GamesController.cs) (Game API), [`backend/src/Services/Game/Game.Application/Games/GameService.cs`](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Application/Games/GameService.cs) (Game workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_frontend["Chess web app<br/>[index.tsx]"]
  node_liveclient["Live game client<br/>[useLiveGame.ts]"]
  node_board3d["3D board renderer<br/>[engine.ts]"]
end

subgraph group_edge["API entry"]
  node_gateway["YARP gateway<br/>[Program.cs]"]
end

subgraph group_services["Chess services"]
  node_identity["Identity and social<br/>[AuthController.cs]"]
  node_gameapi["Game API<br/>[GamesController.cs]"]
  node_gameservice["Game workflows<br/>[GameService.cs]"]
  node_gamedomain["Chess game rules<br/>[Game.cs]"]
  node_realtime["Realtime hub<br/>[GameHub.cs]"]
  node_puzzle["Puzzle solving"]
  node_rating["Ratings and leaderboard"]
  node_ratingconsumer["Rating event consumer"]
  node_tournament["Tournament management"]
  node_tourneyconsumer["Tournament event handler"]
  node_analysis["Position analysis API"]
  node_stockfish["Stockfish engine<br/>[StockfishEngine.cs]"]
end

subgraph group_platform["Messaging and state"]
  node_identitydb[("Identity records")]
  node_gamedb[("Game records<br/>[GameDbContext.cs]")]
  node_puzzledb[("Puzzle records<br/>[PuzzleDbContext.cs]")]
  node_ratingdb[("Rating records<br/>[RatingDbContext.cs]")]
  node_tourneydb[("Tournament records")]
  node_kafka["Kafka events"]
  node_redis[("Redis backplane")]
  node_postgres[("PostgreSQL")]
end

node_player(("Player"))

node_player -->|"uses"| node_frontend
node_frontend -.->|"HTTP requests"| node_gateway
node_frontend -.->|"SignalR connection"| node_gateway
node_frontend -->|"runs live play"| node_liveclient
node_frontend -.->|"renders board"| node_board3d
node_gateway -.->|"routes requests"| node_identity
node_gateway -.->|"routes requests"| node_gameapi
node_gateway -.->|"routes requests"| node_puzzle
node_gateway -.->|"routes requests"| node_rating
node_gateway -.->|"routes requests"| node_tournament
node_gateway -.->|"routes requests"| node_analysis
node_identity -->|"reads and writes"| node_identitydb
node_gameapi -->|"invokes"| node_gameservice
node_gameservice -.->|"validates game state"| node_gamedomain
node_gameservice -.->|"persists games"| node_gamedb
node_liveclient -.->|"sends game actions"| node_gateway
node_gateway -.->|"routes hub"| node_realtime
node_realtime -.->|"broadcasts updates"| node_liveclient
node_puzzle -.->|"loads and records"| node_puzzledb
node_rating -.->|"reads ratings"| node_ratingdb
node_kafka -.->|"delivers events"| node_ratingconsumer
node_ratingconsumer -.->|"updates ratings"| node_ratingdb
node_kafka -.->|"delivers events"| node_tourneyconsumer
node_tourneyconsumer -.->|"updates progress"| node_tourneydb
node_tournament -.->|"reads and writes"| node_tourneydb
node_analysis -.->|"evaluates position"| node_stockfish
node_stockfish -.->|"returns evaluation"| node_analysis
node_realtime -.->|"scales connections"| node_redis
node_gameapi -.->|"publishes game events"| node_kafka
node_puzzle -.->|"publishes attempt events"| node_kafka
node_postgres -.->|"stores data"| node_identitydb
node_postgres -.->|"stores data"| node_gamedb
node_postgres -.->|"stores data"| node_puzzledb
node_postgres -.->|"stores data"| node_ratingdb
node_postgres -.->|"stores data"| node_tourneydb

click node_frontend "https://github.com/haidarmahdi099/online-chess-platform/blob/main/frontend/src/routes/index.tsx"
click node_liveclient "https://github.com/haidarmahdi099/online-chess-platform/blob/main/frontend/src/lib/game/useLiveGame.ts"
click node_board3d "https://github.com/haidarmahdi099/online-chess-platform/blob/main/frontend/src/lib/chess3d/engine.ts"
click node_gateway "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Gateway/Gateway/Program.cs"
click node_identity "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Identity/Identity.Api/Auth/AuthController.cs"
click node_identitydb "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Identity/Identity.Infrastructure/Data/IdentityDbContext.cs"
click node_gameapi "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Api/Controllers/GamesController.cs"
click node_gameservice "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Application/Games/GameService.cs"
click node_gamedomain "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Domain/Entities/Game.cs"
click node_gamedb "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Infrastructure/Persistence/GameDbContext.cs"
click node_realtime "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Realtime/Realtime/Hubs/GameHub.cs"
click node_puzzle "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Puzzle/Puzzle.Api/Controllers/PuzzlesController.cs"
click node_puzzledb "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Puzzle/Puzzle.Infrastructure/Persistence/PuzzleDbContext.cs"
click node_rating "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Rating/Rating.Api/Controllers/RatingsController.cs"
click node_ratingconsumer "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Rating/Rating.Infrastructure/Messaging/RatingEventConsumer.cs"
click node_ratingdb "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Rating/Rating.Infrastructure/Persistence/RatingDbContext.cs"
click node_tournament "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Tournament/Tournament.Api/Controllers/TournamentsController.cs"
click node_tourneyconsumer "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Tournament/Tournament.Infrastructure/Messaging/GameFinishedConsumer.cs"
click node_tourneydb "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Tournament/Tournament.Infrastructure/Persistence/TournamentDbContext.cs"
click node_analysis "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Analysis/Analysis.Api/Controllers/AnalysisController.cs"
click node_stockfish "https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Analysis/Analysis.Infrastructure/Engine/StockfishEngine.cs"

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,node_liveclient,node_board3d toneBlue
class node_gateway toneAmber
class node_identity,node_gameapi,node_gameservice,node_gamedomain,node_realtime,node_puzzle,node_rating,node_ratingconsumer,node_tournament,node_tourneyconsumer,node_analysis,node_stockfish toneMint
class node_identitydb,node_gamedb,node_puzzledb,node_ratingdb,node_tourneydb,node_kafka,node_redis,node_postgres toneRose
class node_player toneIndigo
```

## Components

### Web client

- [Chess web app](https://github.com/haidarmahdi099/online-chess-platform/blob/main/frontend/src/routes/index.tsx): `frontend/src/routes/index.tsx`
- [Live game client](https://github.com/haidarmahdi099/online-chess-platform/blob/main/frontend/src/lib/game/useLiveGame.ts): `frontend/src/lib/game/useLiveGame.ts`
- [3D board renderer](https://github.com/haidarmahdi099/online-chess-platform/blob/main/frontend/src/lib/chess3d/engine.ts): `frontend/src/lib/chess3d/engine.ts`

### API entry

- [YARP gateway](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Gateway/Gateway/Program.cs): `backend/src/Gateway/Gateway/Program.cs`

### Chess services

- [Identity and social](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Identity/Identity.Api/Auth/AuthController.cs): `backend/src/Services/Identity/Identity.Api/Auth/AuthController.cs`
- [Game API](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Api/Controllers/GamesController.cs): `backend/src/Services/Game/Game.Api/Controllers/GamesController.cs`
- [Game workflows](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Application/Games/GameService.cs): `backend/src/Services/Game/Game.Application/Games/GameService.cs`
- [Chess game rules](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Domain/Entities/Game.cs): `backend/src/Services/Game/Game.Domain/Entities/Game.cs`
- [Realtime hub](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Realtime/Realtime/Hubs/GameHub.cs): `backend/src/Services/Realtime/Realtime/Hubs/GameHub.cs`
- [Puzzle solving](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Puzzle/Puzzle.Api/Controllers/PuzzlesController.cs): `backend/src/Services/Puzzle/Puzzle.Api/Controllers/PuzzlesController.cs`
- [Ratings and leaderboard](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Rating/Rating.Api/Controllers/RatingsController.cs): `backend/src/Services/Rating/Rating.Api/Controllers/RatingsController.cs`
- [Rating event consumer](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Rating/Rating.Infrastructure/Messaging/RatingEventConsumer.cs): `backend/src/Services/Rating/Rating.Infrastructure/Messaging/RatingEventConsumer.cs`
- [Tournament management](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Tournament/Tournament.Api/Controllers/TournamentsController.cs): `backend/src/Services/Tournament/Tournament.Api/Controllers/TournamentsController.cs`
- [Tournament event handler](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Tournament/Tournament.Infrastructure/Messaging/GameFinishedConsumer.cs): `backend/src/Services/Tournament/Tournament.Infrastructure/Messaging/GameFinishedConsumer.cs`
- [Position analysis API](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Analysis/Analysis.Api/Controllers/AnalysisController.cs): `backend/src/Services/Analysis/Analysis.Api/Controllers/AnalysisController.cs`
- [Stockfish engine](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Analysis/Analysis.Infrastructure/Engine/StockfishEngine.cs): `backend/src/Services/Analysis/Analysis.Infrastructure/Engine/StockfishEngine.cs`

### Messaging and state

- [Identity records](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Identity/Identity.Infrastructure/Data/IdentityDbContext.cs): `backend/src/Services/Identity/Identity.Infrastructure/Data/IdentityDbContext.cs`
- [Game records](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Game/Game.Infrastructure/Persistence/GameDbContext.cs): `backend/src/Services/Game/Game.Infrastructure/Persistence/GameDbContext.cs`
- [Puzzle records](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Puzzle/Puzzle.Infrastructure/Persistence/PuzzleDbContext.cs): `backend/src/Services/Puzzle/Puzzle.Infrastructure/Persistence/PuzzleDbContext.cs`
- [Rating records](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Rating/Rating.Infrastructure/Persistence/RatingDbContext.cs): `backend/src/Services/Rating/Rating.Infrastructure/Persistence/RatingDbContext.cs`
- [Tournament records](https://github.com/haidarmahdi099/online-chess-platform/blob/main/backend/src/Services/Tournament/Tournament.Infrastructure/Persistence/TournamentDbContext.cs): `backend/src/Services/Tournament/Tournament.Infrastructure/Persistence/TournamentDbContext.cs`
- **Kafka events**
- **Redis backplane**
- **PostgreSQL**

### Other components

- **Player**

## Connections

- Player → Chess web app: uses
- Chess web app → YARP gateway: HTTP requests
- Chess web app → YARP gateway: SignalR connection
- Chess web app → Live game client: runs live play
- Chess web app → 3D board renderer: renders board (evidence: `frontend/src/lib/chess3d/engine.ts`)
- YARP gateway → Identity and social: routes requests
- YARP gateway → Game API: routes requests (evidence: `backend/src/Gateway/Gateway/Program.cs`)
- YARP gateway → Puzzle solving: routes requests
- YARP gateway → Ratings and leaderboard: routes requests
- YARP gateway → Tournament management: routes requests
- YARP gateway → Position analysis API: routes requests
- Identity and social → Identity records: reads and writes (evidence: `backend/src/Services/Identity/Identity.Api/Auth/AuthController.cs`)
- Game API → Game workflows: invokes (evidence: `backend/src/Services/Game/Game.Api/Controllers/GamesController.cs`)
- Game workflows → Chess game rules: validates game state (evidence: `backend/src/Services/Game/Game.Application/Games/GameService.cs`)
- Game workflows → Game records: persists games
- Live game client → YARP gateway: sends game actions
- YARP gateway → Realtime hub: routes hub
- Realtime hub → Live game client: broadcasts updates
- Puzzle solving → Puzzle records: loads and records (evidence: `backend/src/Services/Puzzle/Puzzle.Api/Controllers/PuzzlesController.cs`)
- Ratings and leaderboard → Rating records: reads ratings
- Kafka events → Rating event consumer: delivers events
- Rating event consumer → Rating records: updates ratings
- Kafka events → Tournament event handler: delivers events
- Tournament event handler → Tournament records: updates progress
- Tournament management → Tournament records: reads and writes
- Position analysis API → Stockfish engine: evaluates position
- Stockfish engine → Position analysis API: returns evaluation
- Realtime hub → Redis backplane: scales connections
- Game API → Kafka events: publishes game events
- Puzzle solving → Kafka events: publishes attempt events
- PostgreSQL → Identity records: stores data
- PostgreSQL → Game records: stores data
- PostgreSQL → Puzzle records: stores data
- PostgreSQL → Rating records: stores data
- PostgreSQL → Tournament records: stores data
