# gabriel-logan/stockfish architecture

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

- Interactive diagram: https://gitdiagram.com/gabriel-logan/stockfish
- Repository: https://github.com/gabriel-logan/stockfish

## Overview

Stockfish is a chess platform spanning a React client, a Rust multiplayer API, and a Go Stockfish engine server. Players can play computer games, analyze or study PGNs, save games, and play online. The principal online flow runs from the web client through API routes into room/game handling and live WebSocket coordination; the computer-play and PGN-analysis flows use the separate engine service. Source excerpts show some routing and engine communication, but not all client pages or engine handlers, so unsampled connections are omitted or marked unverified.

Main entry points: [`api/crates/api-server/src/routes.rs`](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/routes.rs) (HTTP and WS routes), [`api/crates/api-server/src/games.rs`](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/games.rs) (Game rules and clocks), [`web/src/App.tsx`](https://github.com/gabriel-logan/stockfish/blob/main/web/src/App.tsx) (Page routing), [`web/src/pages/PlayOnline.tsx`](https://github.com/gabriel-logan/stockfish/blob/main/web/src/pages/PlayOnline.tsx) (Online play)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_app["Page routing<br/>[App.tsx]"]
  node_online["Online play<br/>[PlayOnline.tsx]"]
  node_pgn["PGN review<br/>[PgnViewer.tsx]"]
  node_board["Chess board<br/>[Board.tsx]"]
  node_review["Review analysis<br/>[pgnReview.ts]"]
  node_engineclient["Engine client<br/>[analysisEngine.ts]"]
  node_opening["Opening data<br/>[openings.ts]"]
  node_webapi["API client<br/>[apiInstance.ts]"]
  node_authstate["Auth state<br/>[authStore.ts]"]
end

subgraph group_api["Multiplayer API"]
  node_api_routes["HTTP and WS routes<br/>[routes.rs]"]
  node_auth["Authentication<br/>[auth.rs]"]
  node_rooms["Rooms and matchmaking<br/>[rooms.rs]"]
  node_games["Game rules and clocks<br/>[games.rs]"]
  node_ws["Live game sockets<br/>[ws.rs]"]
  node_hub["Live game hub<br/>[hub.rs]"]
  node_saved["Saved games<br/>[saved_games.rs]"]
  node_users["User profile<br/>[users.rs]"]
  node_models["API data models<br/>[models.rs]"]
end

subgraph group_engine["Chess engine"]
  node_engine_server["Engine server<br/>[main.go]"]
  node_engine_rest["REST engine<br/>[rest.go]"]
  node_engine_ws["Engine WebSocket<br/>[ws.go]"]
  node_stockfish["Stockfish process<br/>[stockfish.go]"]
end

node_player(("Player"))
node_database[("PostgreSQL")]

node_player -->|"uses"| node_app
node_app -->|"routes to"| node_online
node_app -->|"routes to"| node_pgn
node_online -->|"calls API"| node_webapi
node_online -->|"renders"| node_board
node_pgn -->|"renders"| node_board
node_pgn -->|"analyzes moves"| node_review
node_review -->|"requests analysis"| node_engineclient
node_review -->|"looks up openings"| node_opening
node_engineclient -->|"sends analysis"| node_engine_ws
node_webapi -->|"reads tokens"| node_authstate
node_webapi -.->|"sends requests"| node_api_routes
node_api_routes -->|"routes auth"| node_auth
node_api_routes -->|"routes rooms"| node_rooms
node_api_routes -->|"routes games"| node_games
node_api_routes -->|"routes sockets"| node_ws
node_api_routes -->|"routes saves"| node_saved
node_api_routes -->|"routes profile"| node_users
node_ws -->|"coordinates live play"| node_hub
node_ws -->|"dispatches game actions"| node_games
node_rooms -->|"starts games"| node_games
node_auth -->|"uses user records"| node_users
node_auth -->|"reads and writes"| node_database
node_rooms -->|"reads and writes"| node_database
node_games -->|"reads and writes"| node_database
node_saved -->|"stores saved games"| node_database
node_users -->|"reads user data"| node_database
node_engine_server -.->|"serves REST"| node_engine_rest
node_engine_server -.->|"serves WebSocket"| node_engine_ws
node_engine_rest -.->|"uses engine"| node_stockfish
node_engine_ws -.->|"uses engine"| node_stockfish

click node_app "https://github.com/gabriel-logan/stockfish/blob/main/web/src/App.tsx"
click node_online "https://github.com/gabriel-logan/stockfish/blob/main/web/src/pages/PlayOnline.tsx"
click node_pgn "https://github.com/gabriel-logan/stockfish/blob/main/web/src/pages/PgnViewer.tsx"
click node_board "https://github.com/gabriel-logan/stockfish/blob/main/web/src/components/Board.tsx"
click node_review "https://github.com/gabriel-logan/stockfish/blob/main/web/src/utils/pgnReview.ts"
click node_engineclient "https://github.com/gabriel-logan/stockfish/blob/main/web/src/utils/analysisEngine.ts"
click node_opening "https://github.com/gabriel-logan/stockfish/blob/main/web/src/data/openings.ts"
click node_webapi "https://github.com/gabriel-logan/stockfish/blob/main/web/src/lib/apiInstance.ts"
click node_authstate "https://github.com/gabriel-logan/stockfish/blob/main/web/src/store/authStore.ts"
click node_api_routes "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/routes.rs"
click node_auth "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/auth.rs"
click node_rooms "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/rooms.rs"
click node_games "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/games.rs"
click node_ws "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/ws.rs"
click node_hub "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/hub.rs"
click node_saved "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/saved_games.rs"
click node_users "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/users.rs"
click node_models "https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/models.rs"
click node_engine_server "https://github.com/gabriel-logan/stockfish/blob/main/engine/main.go"
click node_engine_rest "https://github.com/gabriel-logan/stockfish/blob/main/engine/rest.go"
click node_engine_ws "https://github.com/gabriel-logan/stockfish/blob/main/engine/ws.go"
click node_stockfish "https://github.com/gabriel-logan/stockfish/blob/main/engine/stockfish.go"

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_app,node_online,node_pgn,node_board,node_review,node_engineclient,node_opening,node_webapi,node_authstate toneBlue
class node_api_routes,node_auth,node_rooms,node_games,node_ws,node_hub,node_saved,node_users,node_models,node_database toneAmber
class node_engine_server,node_engine_rest,node_engine_ws,node_stockfish toneMint
class node_player toneIndigo
```

## Components

### Web client

- [Page routing](https://github.com/gabriel-logan/stockfish/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Online play](https://github.com/gabriel-logan/stockfish/blob/main/web/src/pages/PlayOnline.tsx): `web/src/pages/PlayOnline.tsx`
- [PGN review](https://github.com/gabriel-logan/stockfish/blob/main/web/src/pages/PgnViewer.tsx): `web/src/pages/PgnViewer.tsx`
- [Chess board](https://github.com/gabriel-logan/stockfish/blob/main/web/src/components/Board.tsx): `web/src/components/Board.tsx`
- [Review analysis](https://github.com/gabriel-logan/stockfish/blob/main/web/src/utils/pgnReview.ts): `web/src/utils/pgnReview.ts`
- [Engine client](https://github.com/gabriel-logan/stockfish/blob/main/web/src/utils/analysisEngine.ts): `web/src/utils/analysisEngine.ts`
- [Opening data](https://github.com/gabriel-logan/stockfish/blob/main/web/src/data/openings.ts): `web/src/data/openings.ts`
- [API client](https://github.com/gabriel-logan/stockfish/blob/main/web/src/lib/apiInstance.ts): `web/src/lib/apiInstance.ts`
- [Auth state](https://github.com/gabriel-logan/stockfish/blob/main/web/src/store/authStore.ts): `web/src/store/authStore.ts`

### Multiplayer API

- [HTTP and WS routes](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/routes.rs): `api/crates/api-server/src/routes.rs`
- [Authentication](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/auth.rs): `api/crates/api-server/src/auth.rs`
- [Rooms and matchmaking](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/rooms.rs): `api/crates/api-server/src/rooms.rs`
- [Game rules and clocks](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/games.rs): `api/crates/api-server/src/games.rs`
- [Live game sockets](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/ws.rs): `api/crates/api-server/src/ws.rs`
- [Live game hub](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/hub.rs): `api/crates/api-server/src/hub.rs`
- [Saved games](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/saved_games.rs): `api/crates/api-server/src/saved_games.rs`
- [User profile](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/users.rs): `api/crates/api-server/src/users.rs`
- [API data models](https://github.com/gabriel-logan/stockfish/blob/main/api/crates/api-server/src/models.rs): `api/crates/api-server/src/models.rs`

### Chess engine

- [Engine server](https://github.com/gabriel-logan/stockfish/blob/main/engine/main.go): `engine/main.go`
- [REST engine](https://github.com/gabriel-logan/stockfish/blob/main/engine/rest.go): `engine/rest.go`
- [Engine WebSocket](https://github.com/gabriel-logan/stockfish/blob/main/engine/ws.go): `engine/ws.go`
- [Stockfish process](https://github.com/gabriel-logan/stockfish/blob/main/engine/stockfish.go): `engine/stockfish.go`

### Other components

- **Player**
- **PostgreSQL**

## Connections

- Player → Page routing: uses (evidence: `web/src/App.tsx`)
- Page routing → Online play: routes to (evidence: `web/src/App.tsx`)
- Page routing → PGN review: routes to (evidence: `web/src/App.tsx`)
- Online play → API client: calls API (evidence: `web/src/pages/PlayOnline.tsx`)
- Online play → Chess board: renders (evidence: `web/src/pages/PlayOnline.tsx`)
- PGN review → Chess board: renders (evidence: `web/src/pages/PgnViewer.tsx`)
- PGN review → Review analysis: analyzes moves (evidence: `web/src/pages/PgnViewer.tsx`)
- Review analysis → Engine client: requests analysis (evidence: `web/src/utils/pgnReview.ts`)
- Review analysis → Opening data: looks up openings (evidence: `web/src/utils/pgnReview.ts`)
- Engine client → Engine WebSocket: sends analysis (evidence: `web/src/utils/analysisEngine.ts`)
- API client → Auth state: reads tokens (evidence: `web/src/lib/apiInstance.ts`)
- API client → HTTP and WS routes: sends requests
- HTTP and WS routes → Authentication: routes auth (evidence: `api/crates/api-server/src/routes.rs`)
- HTTP and WS routes → Rooms and matchmaking: routes rooms (evidence: `api/crates/api-server/src/routes.rs`)
- HTTP and WS routes → Game rules and clocks: routes games (evidence: `api/crates/api-server/src/routes.rs`)
- HTTP and WS routes → Live game sockets: routes sockets (evidence: `api/crates/api-server/src/routes.rs`)
- HTTP and WS routes → Saved games: routes saves (evidence: `api/crates/api-server/src/routes.rs`)
- HTTP and WS routes → User profile: routes profile (evidence: `api/crates/api-server/src/routes.rs`)
- Live game sockets → Live game hub: coordinates live play (evidence: `api/crates/api-server/src/ws.rs`)
- Live game sockets → Game rules and clocks: dispatches game actions (evidence: `api/crates/api-server/src/ws.rs`)
- Rooms and matchmaking → Game rules and clocks: starts games (evidence: `api/crates/api-server/src/rooms.rs`)
- Authentication → User profile: uses user records (evidence: `api/crates/api-server/src/auth.rs`)
- Authentication → PostgreSQL: reads and writes (evidence: `api/crates/api-server/src/auth.rs`)
- Rooms and matchmaking → PostgreSQL: reads and writes (evidence: `api/crates/api-server/src/rooms.rs`)
- Game rules and clocks → PostgreSQL: reads and writes (evidence: `api/crates/api-server/src/games.rs`)
- Saved games → PostgreSQL: stores saved games (evidence: `api/crates/api-server/src/saved_games.rs`)
- User profile → PostgreSQL: reads user data (evidence: `api/crates/api-server/src/users.rs`)
- Engine server → REST engine: serves REST
- Engine server → Engine WebSocket: serves WebSocket
- REST engine → Stockfish process: uses engine
- Engine WebSocket → Stockfish process: uses engine