# minki-art/number-duel architecture

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

- Interactive diagram: https://gitdiagram.com/minki-art/number-duel
- Repository: https://github.com/minki-art/number-duel

## Overview

Number Duel is a server-authoritative, turn-based browser game supporting single-player against four AI levels and LAN/online multiplayer. Players use the browser to create or join a room, take turns choosing an operation, and receive updated game state; the server validates actions, applies rules, and broadcasts results. The documented skills, anti-stalemate rules, room invitations, and AI search are represented. The browser implementation was not sampled, so its internal behavior is shown only at the documented client/server boundary.

Main entry points: [`server.py`](https://github.com/minki-art/number-duel/blob/main/server.py) (WebSocket play), [`web/index.html`](https://github.com/minki-art/number-duel/blob/main/web/index.html) (Game UI), [`game_engine.py`](https://github.com/minki-art/number-duel/blob/main/game_engine.py) (Game engine), [`ai.py`](https://github.com/minki-art/number-duel/blob/main/ai.py) (AI difficulty selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_browser["Game UI<br/>[index.html]"]
end

subgraph group_service["Game service"]
  node_room_api["Room APIs<br/>[server.py]"]
  node_room_coord["Room coordination<br/>[server.py]"]
  node_ws_flow["WebSocket play<br/>[server.py]"]
  node_state_view["State broadcast<br/>[server.py]"]
end

subgraph group_game["Game rules"]
  node_engine["Game engine<br/>[game_engine.py]"]
  node_action_rules["Action resolution<br/>[game_engine.py]"]
  node_skills["Skills and endings<br/>[game_engine.py]"]
end

subgraph group_strategy["AI strategy"]
  node_ai_factory["AI difficulty selection<br/>[ai.py]"]
  node_ai_search["AI move search<br/>[ai.py]"]
end

node_player(("Player"))

node_player -->|"plays through"| node_browser
node_browser -->|"creates or joins"| node_room_api
node_browser -->|"sends moves"| node_ws_flow
node_room_api -->|"creates rooms"| node_room_coord
node_room_coord -->|"coordinates seats"| node_ws_flow
node_ws_flow -->|"executes actions"| node_engine
node_ws_flow -->|"requests AI moves"| node_ai_factory
node_ai_factory -->|"selects strategy"| node_ai_search
node_ai_search -->|"simulates actions"| node_engine
node_engine -->|"resolves turns"| node_action_rules
node_action_rules -->|"checks skills"| node_skills
node_ws_flow -->|"broadcasts updates"| node_state_view
node_state_view -->|"sends game state"| node_browser

click node_browser "https://github.com/minki-art/number-duel/blob/main/web/index.html"
click node_room_api "https://github.com/minki-art/number-duel/blob/main/server.py"
click node_room_coord "https://github.com/minki-art/number-duel/blob/main/server.py"
click node_ws_flow "https://github.com/minki-art/number-duel/blob/main/server.py"
click node_state_view "https://github.com/minki-art/number-duel/blob/main/server.py"
click node_engine "https://github.com/minki-art/number-duel/blob/main/game_engine.py"
click node_action_rules "https://github.com/minki-art/number-duel/blob/main/game_engine.py"
click node_skills "https://github.com/minki-art/number-duel/blob/main/game_engine.py"
click node_ai_factory "https://github.com/minki-art/number-duel/blob/main/ai.py"
click node_ai_search "https://github.com/minki-art/number-duel/blob/main/ai.py"

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_browser toneBlue
class node_room_api,node_room_coord,node_ws_flow,node_state_view toneAmber
class node_engine,node_action_rules,node_skills toneMint
class node_ai_factory,node_ai_search toneRose
class node_player toneIndigo
```

## Components

### Browser client

- [Game UI](https://github.com/minki-art/number-duel/blob/main/web/index.html): `web/index.html`

### Game service

- [Room APIs](https://github.com/minki-art/number-duel/blob/main/server.py): `server.py`
- [Room coordination](https://github.com/minki-art/number-duel/blob/main/server.py): `server.py`
- [WebSocket play](https://github.com/minki-art/number-duel/blob/main/server.py): `server.py`
- [State broadcast](https://github.com/minki-art/number-duel/blob/main/server.py): `server.py`

### Game rules

- [Game engine](https://github.com/minki-art/number-duel/blob/main/game_engine.py): `game_engine.py`
- [Action resolution](https://github.com/minki-art/number-duel/blob/main/game_engine.py): `game_engine.py`
- [Skills and endings](https://github.com/minki-art/number-duel/blob/main/game_engine.py): `game_engine.py`

### AI strategy

- [AI difficulty selection](https://github.com/minki-art/number-duel/blob/main/ai.py): `ai.py`
- [AI move search](https://github.com/minki-art/number-duel/blob/main/ai.py): `ai.py`

### Other components

- **Player**

## Connections

- Player → Game UI: plays through (evidence: `README.md`)
- Game UI → Room APIs: creates or joins (evidence: `README.md`)
- Game UI → WebSocket play: sends moves (evidence: `README.md`)
- Room APIs → Room coordination: creates rooms (evidence: `server.py`)
- Room coordination → WebSocket play: coordinates seats (evidence: `server.py`)
- WebSocket play → Game engine: executes actions (evidence: `server.py`)
- WebSocket play → AI difficulty selection: requests AI moves (evidence: `server.py`)
- AI difficulty selection → AI move search: selects strategy (evidence: `ai.py`)
- AI move search → Game engine: simulates actions (evidence: `ai.py`)
- Game engine → Action resolution: resolves turns (evidence: `game_engine.py`)
- Action resolution → Skills and endings: checks skills (evidence: `game_engine.py`)
- WebSocket play → State broadcast: broadcasts updates (evidence: `server.py`)
- State broadcast → Game UI: sends game state (evidence: `server.py`)
