# saainikhil/least-count architecture

> Architecture diagram of the GitHub repository saainikhil/least-count, 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/saainikhil/least-count
- Repository: https://github.com/saainikhil/least-count

## Overview

Least Count is a real-time multiplayer card game with a React client and an authoritative Socket.IO server, plus a local System Bot mode. The main workflow is to create or join a room, ready up, play setup and turn actions, and view round and final scores; players can also start a bot game or consult rules and customize themes. The README documents reconnect recovery and sanitized player views. Some client and server implementation details are unsampled, so those links rely on README statements rather than inferred source calls.

Main entry points: [`frontend/src/main.tsx`](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/main.tsx) (App coordinator), [`backend/server.ts`](https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/server.ts) (Socket.IO server), [`frontend/src/components/Table.tsx`](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/Table.tsx) (Game table), [`backend/src/game/engine.ts`](https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/src/game/engine.ts) (Game engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["App coordinator<br/>[main.tsx]"]
  node_home["Home screen<br/>[HomePage.tsx]"]
  node_friends["Friends rooms<br/>[FriendsPage.tsx]"]
  node_lobby["Room lobby<br/>[LobbyPage.tsx]"]
  node_table["Game table<br/>[Table.tsx]"]
  node_card["Card renderer<br/>[Card.tsx]"]
  node_scores["Score modal<br/>[ScoreModal.tsx]"]
  node_gameover["Game result modal<br/>[GameOverModal.tsx]"]
  node_settings["Theme settings<br/>[SettingsPage.tsx]"]
  node_rules["Rules guide<br/>[RulesPage.tsx]"]
  node_clienttypes["Client game types<br/>[game.ts]"]
end

subgraph group_server["Realtime server"]
  node_socketserver["Socket.IO server<br/>[server.ts]"]
  node_rooms[("Room sessions<br/>[server.ts]")]
  node_viewerstate["Viewer state<br/>[server.ts]"]
end

subgraph group_game["Game runtime"]
  node_engine["Game engine<br/>[engine.ts]"]
  node_protocol["Game protocol<br/>[game.ts]"]
  node_frontendengine["Engine facade<br/>[engine.ts]"]
  node_bot["System Bot<br/>[systemBot.ts]"]
end

subgraph group_product["Game experience"]
end

node_player(("Player"))

node_player -->|"uses"| node_app
node_app -->|"sends room actions"| node_socketserver
node_socketserver -->|"manages sessions"| node_rooms
node_socketserver -->|"validates actions"| node_engine
node_socketserver -->|"broadcasts sanitized views"| node_viewerstate
node_viewerstate -->|"sends game state"| node_app
node_app -->|"renders"| node_home
node_app -->|"renders"| node_friends
node_app -->|"renders"| node_lobby
node_app -->|"renders"| node_table
node_app -->|"renders"| node_scores
node_app -->|"renders"| node_gameover
node_app -->|"renders"| node_settings
node_app -->|"renders"| node_rules
node_app -->|"runs local game"| node_engine
node_app -->|"runs bot turns"| node_bot
node_table -->|"renders cards"| node_card
node_table -->|"scores hand"| node_frontendengine
node_frontendengine -->|"re-exports"| node_engine
node_bot -->|"uses rules"| node_frontendengine
node_engine -->|"uses game types"| node_protocol
node_socketserver -->|"uses state schemas"| node_protocol
node_app -->|"uses client state"| node_clienttypes
node_table -->|"renders typed state"| node_clienttypes
node_rules -->|"shows examples"| node_card

click node_app "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/main.tsx"
click node_home "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/HomePage.tsx"
click node_friends "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/FriendsPage.tsx"
click node_lobby "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/LobbyPage.tsx"
click node_table "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/Table.tsx"
click node_card "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/Card.tsx"
click node_scores "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/ScoreModal.tsx"
click node_gameover "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/GameOverModal.tsx"
click node_settings "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/SettingsPage.tsx"
click node_rules "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/RulesPage.tsx"
click node_socketserver "https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/server.ts"
click node_rooms "https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/server.ts"
click node_viewerstate "https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/server.ts"
click node_engine "https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/src/game/engine.ts"
click node_protocol "https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/src/types/game.ts"
click node_clienttypes "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/types/game.ts"
click node_frontendengine "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/game/engine.ts"
click node_bot "https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/game/systemBot.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_app,node_home,node_friends,node_lobby,node_table,node_card,node_scores,node_gameover,node_settings,node_rules,node_clienttypes toneBlue
class node_socketserver,node_rooms,node_viewerstate toneAmber
class node_engine,node_protocol,node_frontendengine,node_bot toneMint
class node_player toneIndigo
```

## Components

### Web client

- [App coordinator](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/main.tsx): `frontend/src/main.tsx`
- [Home screen](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/HomePage.tsx): `frontend/src/pages/HomePage.tsx`
- [Friends rooms](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/FriendsPage.tsx): `frontend/src/pages/FriendsPage.tsx`
- [Room lobby](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/LobbyPage.tsx): `frontend/src/pages/LobbyPage.tsx`
- [Game table](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/Table.tsx): `frontend/src/components/Table.tsx`
- [Card renderer](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/Card.tsx): `frontend/src/components/Card.tsx`
- [Score modal](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/ScoreModal.tsx): `frontend/src/components/ScoreModal.tsx`
- [Game result modal](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/components/GameOverModal.tsx): `frontend/src/components/GameOverModal.tsx`
- [Theme settings](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/SettingsPage.tsx): `frontend/src/pages/SettingsPage.tsx`
- [Rules guide](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/pages/RulesPage.tsx): `frontend/src/pages/RulesPage.tsx`
- [Client game types](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/types/game.ts): `frontend/src/types/game.ts`

### Realtime server

- [Socket.IO server](https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/server.ts): `backend/server.ts`
- [Room sessions](https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/server.ts): `backend/server.ts`
- [Viewer state](https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/server.ts): `backend/server.ts`

### Game runtime

- [Game engine](https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/src/game/engine.ts): `backend/src/game/engine.ts`
- [Game protocol](https://github.com/saainikhil/least-count/blob/leastcount-dev/backend/src/types/game.ts): `backend/src/types/game.ts`
- [Engine facade](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/game/engine.ts): `frontend/src/game/engine.ts`
- [System Bot](https://github.com/saainikhil/least-count/blob/leastcount-dev/frontend/src/game/systemBot.ts): `frontend/src/game/systemBot.ts`

### Other components

- **Player**

## Connections

- Player → App coordinator: uses (evidence: `README.md`)
- App coordinator → Socket.IO server: sends room actions (evidence: `README.md`)
- Socket.IO server → Room sessions: manages sessions (evidence: `backend/server.ts`)
- Socket.IO server → Game engine: validates actions (evidence: `README.md`)
- Socket.IO server → Viewer state: broadcasts sanitized views (evidence: `README.md`)
- Viewer state → App coordinator: sends game state (evidence: `README.md`)
- App coordinator → Home screen: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Friends rooms: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Room lobby: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Game table: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Score modal: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Game result modal: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Theme settings: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Rules guide: renders (evidence: `frontend/src/main.tsx`)
- App coordinator → Game engine: runs local game (evidence: `README.md`)
- App coordinator → System Bot: runs bot turns (evidence: `frontend/src/main.tsx`)
- Game table → Card renderer: renders cards (evidence: `frontend/src/components/Table.tsx`)
- Game table → Engine facade: scores hand (evidence: `frontend/src/components/Table.tsx`)
- Engine facade → Game engine: re-exports (evidence: `frontend/src/game/engine.ts`)
- System Bot → Engine facade: uses rules (evidence: `frontend/src/game/systemBot.ts`)
- Game engine → Game protocol: uses game types (evidence: `backend/src/game/engine.ts`)
- Socket.IO server → Game protocol: uses state schemas (evidence: `backend/server.ts`)
- App coordinator → Client game types: uses client state (evidence: `frontend/src/main.tsx`)
- Game table → Client game types: renders typed state (evidence: `frontend/src/components/Table.tsx`)
- Rules guide → Card renderer: shows examples (evidence: `frontend/src/pages/RulesPage.tsx`)
