# sm41l27/kazdoyby_public architecture

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

- Interactive diagram: https://gitdiagram.com/sm41l27/kazdoyby_public
- Repository: https://github.com/sm41l27/kazdoyby_public

## Overview

This repository implements a Kazakh-language 2v2 board game with AI, online rooms, tournament play, social features, and customizable avatars. Players enter through the browser UI, connect to the Socket.IO server, join or create a room, then play turns; tournament turns are validated and advanced by a worker-backed authoritative engine. The browser also exposes offline play and social, avatar, and tournament capabilities. Server/database integrations and several frontend modules are only documented by the source index or unsampled code, so those links are omitted where their runtime relationships cannot be verified.

Main entry points: [`server.js`](https://github.com/sm41l27/kazdoyby_public/blob/main/server.js) (HTTP and Socket server), [`tournament-play.js`](https://github.com/sm41l27/kazdoyby_public/blob/main/tournament-play.js) (Tournament turns), [`avatars-server.js`](https://github.com/sm41l27/kazdoyby_public/blob/main/avatars-server.js) (Avatar service), [`tournament-server.js`](https://github.com/sm41l27/kazdoyby_public/blob/main/tournament-server.js) (Tournament service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser experience"]
  node_webapp["App navigation<br/>[app.js]"]
  node_gameui["Game interface<br/>[game-core.js]"]
  node_netclient["Network client<br/>[network.js]"]
  node_authui["Authentication<br/>[auth.js]"]
  node_roomui["Room interface<br/>[room.js]"]
  node_socialui["Social interface<br/>[social.js]"]
  node_avatarui["Avatar editor<br/>[avatar-ui.js]"]
end

subgraph group_realtime["Rooms and play"]
  node_server["HTTP and Socket server<br/>[server.js]"]
  node_roomcontrol["Room control<br/>[room-control.js]"]
end

subgraph group_competition["Tournament play"]
  node_tournamentplay["Tournament turns<br/>[tournament-play.js]"]
  node_tournamentapi["Tournament service"]
end

subgraph group_community["Social and identity"]
  node_socialserver["Social service<br/>[social-server.js]"]
  node_avatarserver["Avatar service<br/>[avatars-server.js]"]
end

subgraph group_engine["Game engine"]
  node_gameengine["Turn rules<br/>[game-engine.js]"]
  node_gamecore["Shared game rules<br/>[game-core.js]"]
  node_turnpool["Worker pool<br/>[turn-pool.js]"]
  node_turnworker["Turn worker<br/>[turn-worker.js]"]
end

node_player(("Player"))
node_database[("Supabase backend")]

node_player -->|"uses"| node_webapp
node_webapp -->|"opens play"| node_gameui
node_player -.->|"manages rooms"| node_roomui
node_player -.->|"uses"| node_socialui
node_player -.->|"edits avatar"| node_avatarui
node_netclient -.->|"Socket.IO"| node_server
node_server -->|"registers room control"| node_roomcontrol
node_server -->|"registers social service"| node_socialserver
node_server -->|"registers tournament service"| node_tournamentapi
node_server -->|"registers avatar service"| node_avatarserver
node_server -->|"initializes tournament"| node_tournamentplay
node_tournamentplay -->|"advances turns"| node_gameengine
node_gameengine -->|"uses rules"| node_gamecore
node_tournamentplay -->|"submits jobs"| node_turnpool
node_turnpool -->|"dispatches jobs"| node_turnworker
node_turnworker -->|"runs step"| node_gameengine
node_tournamentapi -->|"RPC requests"| node_database
node_socialserver -->|"RPC requests"| node_database
node_avatarserver -->|"reads and writes"| node_database
node_avatarserver -->|"serves photos"| node_player
node_roomcontrol -->|"updates seats"| node_tournamentapi

click node_webapp "https://github.com/sm41l27/kazdoyby_public/blob/main/public/app.js"
click node_gameui "https://github.com/sm41l27/kazdoyby_public/blob/main/public/game-core.js"
click node_netclient "https://github.com/sm41l27/kazdoyby_public/blob/main/public/network.js"
click node_authui "https://github.com/sm41l27/kazdoyby_public/blob/main/public/auth.js"
click node_roomui "https://github.com/sm41l27/kazdoyby_public/blob/main/public/room.js"
click node_socialui "https://github.com/sm41l27/kazdoyby_public/blob/main/public/social.js"
click node_avatarui "https://github.com/sm41l27/kazdoyby_public/blob/main/public/avatar-ui.js"
click node_server "https://github.com/sm41l27/kazdoyby_public/blob/main/server.js"
click node_roomcontrol "https://github.com/sm41l27/kazdoyby_public/blob/main/room-control.js"
click node_tournamentplay "https://github.com/sm41l27/kazdoyby_public/blob/main/tournament-play.js"
click node_tournamentapi "https://github.com/sm41l27/kazdoyby_public/blob/main/tournament-server.js"
click node_socialserver "https://github.com/sm41l27/kazdoyby_public/blob/main/social-server.js"
click node_avatarserver "https://github.com/sm41l27/kazdoyby_public/blob/main/avatars-server.js"
click node_gameengine "https://github.com/sm41l27/kazdoyby_public/blob/main/game-engine.js"
click node_gamecore "https://github.com/sm41l27/kazdoyby_public/blob/main/public/game-core.js"
click node_turnpool "https://github.com/sm41l27/kazdoyby_public/blob/main/turn-pool.js"
click node_turnworker "https://github.com/sm41l27/kazdoyby_public/blob/main/turn-worker.js"

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_gameui,node_netclient,node_authui,node_roomui,node_socialui,node_avatarui toneBlue
class node_server,node_roomcontrol,node_database toneAmber
class node_tournamentplay,node_tournamentapi toneMint
class node_socialserver,node_avatarserver toneRose
class node_gameengine,node_gamecore,node_turnpool,node_turnworker,node_player toneIndigo
```

## Components

### Browser experience

- [App navigation](https://github.com/sm41l27/kazdoyby_public/blob/main/public/app.js): `public/app.js`
- [Game interface](https://github.com/sm41l27/kazdoyby_public/blob/main/public/game-core.js): `public/game-core.js`
- [Network client](https://github.com/sm41l27/kazdoyby_public/blob/main/public/network.js): `public/network.js`
- [Authentication](https://github.com/sm41l27/kazdoyby_public/blob/main/public/auth.js): `public/auth.js`
- [Room interface](https://github.com/sm41l27/kazdoyby_public/blob/main/public/room.js): `public/room.js`
- [Social interface](https://github.com/sm41l27/kazdoyby_public/blob/main/public/social.js): `public/social.js`
- [Avatar editor](https://github.com/sm41l27/kazdoyby_public/blob/main/public/avatar-ui.js): `public/avatar-ui.js`

### Rooms and play

- [HTTP and Socket server](https://github.com/sm41l27/kazdoyby_public/blob/main/server.js): `server.js`
- [Room control](https://github.com/sm41l27/kazdoyby_public/blob/main/room-control.js): `room-control.js`

### Tournament play

- [Tournament turns](https://github.com/sm41l27/kazdoyby_public/blob/main/tournament-play.js): `tournament-play.js`
- [Tournament service](https://github.com/sm41l27/kazdoyby_public/blob/main/tournament-server.js): `tournament-server.js`

### Social and identity

- [Social service](https://github.com/sm41l27/kazdoyby_public/blob/main/social-server.js): `social-server.js`
- [Avatar service](https://github.com/sm41l27/kazdoyby_public/blob/main/avatars-server.js): `avatars-server.js`

### Game engine

- [Turn rules](https://github.com/sm41l27/kazdoyby_public/blob/main/game-engine.js): `game-engine.js`
- [Shared game rules](https://github.com/sm41l27/kazdoyby_public/blob/main/public/game-core.js): `public/game-core.js`
- [Worker pool](https://github.com/sm41l27/kazdoyby_public/blob/main/turn-pool.js): `turn-pool.js`
- [Turn worker](https://github.com/sm41l27/kazdoyby_public/blob/main/turn-worker.js): `turn-worker.js`

### Other components

- **Player**
- **Supabase backend**

## Connections

- Player → App navigation: uses (evidence: `public/app.js`)
- App navigation → Game interface: opens play (evidence: `public/app.js`)
- Player → Room interface: manages rooms
- Player → Social interface: uses
- Player → Avatar editor: edits avatar
- Network client → HTTP and Socket server: Socket.IO
- HTTP and Socket server → Room control: registers room control (evidence: `server.js`)
- HTTP and Socket server → Social service: registers social service (evidence: `server.js`)
- HTTP and Socket server → Tournament service: registers tournament service (evidence: `server.js`)
- HTTP and Socket server → Avatar service: registers avatar service (evidence: `server.js`)
- HTTP and Socket server → Tournament turns: initializes tournament (evidence: `server.js`)
- Tournament turns → Turn rules: advances turns (evidence: `tournament-play.js`)
- Turn rules → Shared game rules: uses rules (evidence: `game-engine.js`)
- Tournament turns → Worker pool: submits jobs (evidence: `tournament-play.js`)
- Worker pool → Turn worker: dispatches jobs (evidence: `turn-pool.js`)
- Turn worker → Turn rules: runs step (evidence: `turn-worker.js`)
- Tournament service → Supabase backend: RPC requests (evidence: `tournament-server.js`)
- Social service → Supabase backend: RPC requests (evidence: `social-server.js`)
- Avatar service → Supabase backend: reads and writes (evidence: `avatars-server.js`)
- Avatar service → Player: serves photos (evidence: `avatars-server.js`)
- Room control → Tournament service: updates seats (evidence: `room-control.js`)
