# nikolayit/belotgameengine architecture

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

- Interactive diagram: https://gitdiagram.com/nikolayit/belotgameengine
- Repository: https://github.com/nikolayit/belotgameengine

## Overview

Belot Game Engine is both a reusable trick-taking rules engine and the core of a MAUI game where a person plays South against configurable opponents. The engine runs bids, declarations, legal card play, tricks, and scoring; player implementations supply decisions. The app presents the match and retains local rating and history. The README documents several AI styles, though not all are represented by sampled source. Edges reflect README claims or source-index references; unsampled UI and AI wiring is left unverified.

Main entry points: [`src/Belot.Engine/GameMechanics/RoundManager.cs`](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/RoundManager.cs) (Round orchestration), [`src/Belot.Engine/Players/IPlayer.cs`](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/Players/IPlayer.cs) (Player interface), [`src/UI/Belot.UI/Pages/StartPage.xaml.cs`](https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/Pages/StartPage.xaml.cs) (Game interface), [`src/UI/Belot.UI/App.xaml.cs`](https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/App.xaml.cs) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Game engine"]
  node_game["Match orchestration<br/>[BelotGame.cs]"]
  node_round["Round orchestration<br/>[RoundManager.cs]"]
  node_bidding["Bidding and contract<br/>[ContractManager.cs]"]
  node_announces["Announcements<br/>[Announce.cs]"]
  node_tricks["Trick play<br/>[TricksManager.cs]"]
  node_legality["Valid plays"]
  node_scoring["Round scoring<br/>[ScoreManager.cs]"]
  node_cards["Card collection<br/>[CardCollection.cs]"]
  node_playerapi["Player interface<br/>[IPlayer.cs]"]
end

subgraph group_players["Player strategies"]
  node_smart["Smart strategy<br/>[SmartPlayer.cs]"]
  node_neural["Neural player"]
  node_heuristic["Heuristic player"]
  node_search["Neural search<br/>[NeuralSearch.cs]"]
  node_random["Random player<br/>[RandomPlayer.cs]"]
  node_master["Master profile"]
end

subgraph group_app["Mobile app"]
  node_appstart["App entry<br/>[App.xaml.cs]"]
  node_session["Game session<br/>[GameSession.cs]"]
  node_gameui["Game interface<br/>[StartPage.xaml.cs]"]
end

subgraph group_state["Local game records"]
  node_records[("Player records<br/>[Game]")]
end

node_human(("Human player"))

node_human -->|"plays through"| node_gameui
node_gameui -.->|"starts match"| node_session
node_session -.->|"runs"| node_game
node_game -.->|"plays rounds"| node_round
node_round -.->|"requests bids"| node_bidding
node_round -.->|"records declarations"| node_announces
node_round -.->|"plays tricks"| node_tricks
node_round -.->|"scores round"| node_scoring
node_round -->|"uses cards"| node_cards
node_round -->|"drives players"| node_playerapi
node_tricks -.->|"checks plays"| node_legality
node_scoring -->|"reads round result"| node_round
node_playerapi -.->|"implemented by"| node_smart
node_playerapi -.->|"implemented by"| node_neural
node_playerapi -.->|"implemented by"| node_heuristic
node_playerapi -.->|"implemented by"| node_random
node_neural -.->|"search-enhanced option"| node_search
node_playerapi -.->|"profile variant"| node_master
node_appstart -.->|"opens"| node_gameui
node_appstart -.->|"retains ratings"| node_records
node_appstart -->|"localizes app"| node_gameui

click node_appstart "https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/App.xaml.cs"
click node_session "https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/Game/GameSession.cs"
click node_gameui "https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/Pages/StartPage.xaml.cs"
click node_records "https://github.com/nikolayit/belotgameengine/tree/master/src/UI/Belot.UI/Game"
click node_game "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/BelotGame.cs"
click node_round "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/RoundManager.cs"
click node_bidding "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/ContractManager.cs"
click node_announces "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/Game/Announce.cs"
click node_tricks "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/TricksManager.cs"
click node_legality "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/ValidAnnouncesService.cs"
click node_scoring "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/ScoreManager.cs"
click node_cards "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/Cards/CardCollection.cs"
click node_playerapi "https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/Players/IPlayer.cs"
click node_smart "https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.SmartPlayer/SmartPlayer.cs"
click node_neural "https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.ClaudePlayer/ClaudePlayerNeural.cs"
click node_heuristic "https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.ClaudePlayer/Heuristic/HeuristicCardPlay.cs"
click node_search "https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.ClaudePlayer/Neural/NeuralSearch.cs"
click node_random "https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.DummyPlayer/RandomPlayer.cs"
click node_master "https://github.com/nikolayit/belotgameengine/tree/master/src/AI/Belot.AI.ClaudePlayer"

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_game,node_round,node_bidding,node_announces,node_tricks,node_legality,node_scoring,node_cards,node_playerapi toneBlue
class node_smart,node_neural,node_heuristic,node_search,node_random,node_master toneAmber
class node_appstart,node_session,node_gameui toneMint
class node_records toneRose
class node_human toneIndigo
```

## Components

### Game engine

- [Match orchestration](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/BelotGame.cs): `src/Belot.Engine/BelotGame.cs`
- [Round orchestration](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/RoundManager.cs): `src/Belot.Engine/GameMechanics/RoundManager.cs`
- [Bidding and contract](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/ContractManager.cs): `src/Belot.Engine/GameMechanics/ContractManager.cs`
- [Announcements](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/Game/Announce.cs): `src/Belot.Engine/Game/Announce.cs`
- [Trick play](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/TricksManager.cs): `src/Belot.Engine/GameMechanics/TricksManager.cs`
- [Valid plays](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/ValidAnnouncesService.cs): `src/Belot.Engine/GameMechanics/ValidAnnouncesService.cs`
- [Round scoring](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/GameMechanics/ScoreManager.cs): `src/Belot.Engine/GameMechanics/ScoreManager.cs`
- [Card collection](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/Cards/CardCollection.cs): `src/Belot.Engine/Cards/CardCollection.cs`
- [Player interface](https://github.com/nikolayit/belotgameengine/blob/master/src/Belot.Engine/Players/IPlayer.cs): `src/Belot.Engine/Players/IPlayer.cs`

### Player strategies

- [Smart strategy](https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.SmartPlayer/SmartPlayer.cs): `src/AI/Belot.AI.SmartPlayer/SmartPlayer.cs`
- [Neural player](https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.ClaudePlayer/ClaudePlayerNeural.cs): `src/AI/Belot.AI.ClaudePlayer/ClaudePlayerNeural.cs`
- [Heuristic player](https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.ClaudePlayer/Heuristic/HeuristicCardPlay.cs): `src/AI/Belot.AI.ClaudePlayer/Heuristic/HeuristicCardPlay.cs`
- [Neural search](https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.ClaudePlayer/Neural/NeuralSearch.cs): `src/AI/Belot.AI.ClaudePlayer/Neural/NeuralSearch.cs`
- [Random player](https://github.com/nikolayit/belotgameengine/blob/master/src/AI/Belot.AI.DummyPlayer/RandomPlayer.cs): `src/AI/Belot.AI.DummyPlayer/RandomPlayer.cs`
- [Master profile](https://github.com/nikolayit/belotgameengine/tree/master/src/AI/Belot.AI.ClaudePlayer): `src/AI/Belot.AI.ClaudePlayer`

### Mobile app

- [App entry](https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/App.xaml.cs): `src/UI/Belot.UI/App.xaml.cs`
- [Game session](https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/Game/GameSession.cs): `src/UI/Belot.UI/Game/GameSession.cs`
- [Game interface](https://github.com/nikolayit/belotgameengine/blob/master/src/UI/Belot.UI/Pages/StartPage.xaml.cs): `src/UI/Belot.UI/Pages/StartPage.xaml.cs`

### Local game records

- [Player records](https://github.com/nikolayit/belotgameengine/tree/master/src/UI/Belot.UI/Game): `src/UI/Belot.UI/Game`

### Other components

- **Human player**

## Connections

- Human player → Game interface: plays through
- Game interface → Game session: starts match
- Game session → Match orchestration: runs
- Match orchestration → Round orchestration: plays rounds
- Round orchestration → Bidding and contract: requests bids
- Round orchestration → Announcements: records declarations
- Round orchestration → Trick play: plays tricks
- Round orchestration → Round scoring: scores round
- Round orchestration → Card collection: uses cards (evidence: `src/Belot.Engine/GameMechanics/RoundManager.cs`)
- Round orchestration → Player interface: drives players (evidence: `src/Belot.Engine/GameMechanics/RoundManager.cs`)
- Trick play → Valid plays: checks plays
- Round scoring → Round orchestration: reads round result (evidence: `src/Belot.Engine/GameMechanics/ScoreManager.cs`)
- Player interface → Smart strategy: implemented by
- Player interface → Neural player: implemented by
- Player interface → Heuristic player: implemented by
- Player interface → Random player: implemented by
- Neural player → Neural search: search-enhanced option
- Player interface → Master profile: profile variant
- App entry → Game interface: opens
- App entry → Player records: retains ratings
- App entry → Game interface: localizes app (evidence: `src/UI/Belot.UI/App.xaml.cs`)
