# vvbocko/mindduck architecture

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

## Overview

MindDuckServer is the backend for a Unity multiplayer card game. Players request a room, connect over WebSocket, and exchange game commands and state; the server manages rooms and matches while the rules engine applies turns and decisions. The code excerpts show the room API, WebSocket dispatch, in-memory room management, and rules behavior. The README establishes PostgreSQL as a runtime dependency; repository implementations and registrations are indexed, but their runtime call paths beyond card listing are not established by the excerpts.

Main entry points: [`MindDuckServer/src/MindDuck.Rules/GameEngine.cs`](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/GameEngine.cs) (Game Engine), [`MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs`](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs) (Fake Engine), [`MindDuckServer/src/MindDuck.Server/Program.cs`](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/Program.cs) (HTTP/WebSocket Host), [`MindDuckServer/src/MindDuck.Server/WebSockets/GameWebSocketHandler.cs`](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/WebSockets/GameWebSocketHandler.cs) (Game Socket Handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Server API"]
  node_server["HTTP/WebSocket Host<br/>[Program.cs]"]
  node_socket["Game Socket Handler"]
end

subgraph group_session["Rooms and Matches"]
  node_roommgr["Room Manager<br/>[RoomManager.cs]"]
  node_room["Room State<br/>[Room.cs]"]
  node_matchmgr["Match Manager<br/>[MatchManager.cs]"]
end

subgraph group_rules["Game Rules"]
  node_match["Match State<br/>[Match.cs]"]
  node_service["Game Service<br/>[GameService.cs]"]
  node_engine["Game Engine<br/>[GameEngine.cs]"]
  node_fakeengine["Fake Engine<br/>[FakeGameEngine.cs]"]
  node_state["Game State<br/>[GameState.cs]"]
  node_players["Player and Card Model<br/>[Player.cs]"]
  node_board["Board and Zones<br/>[Board.cs]"]
  node_card["Card Mechanics<br/>[Card.cs]"]
  node_commands["Player Commands<br/>[GameCommand.cs]"]
  node_results["Apply Results<br/>[ApplyResult.cs]"]
  node_combat["Combat Rules<br/>[CombatRules.cs]"]
end

subgraph group_persistence["Card Persistence"]
  node_cardrepo["Card Repository"]
  node_matchrepo["Match Repository"]
  node_playerrepo["Player Repository"]
  node_postgres[("PostgreSQL")]
end

subgraph group_contracts["Client Protocol"]
  node_contracts["Wire Message DTOs<br/>[ClientMessages.cs]"]
  node_stateview["State View DTO<br/>[GameStateView.cs]"]
  node_restdto["REST DTOs<br/>[RestDtos.cs]"]
end

node_player(("Unity Player"))

node_player -->|"requests"| node_server
node_server -->|"creates room"| node_roommgr
node_roommgr -->|"stores"| node_room
node_player -.->|"sends commands"| node_socket
node_server -->|"dispatches"| node_socket
node_socket -->|"looks up rooms"| node_roommgr
node_matchmgr -->|"stores"| node_match
node_service -->|"manages matches"| node_matchmgr
node_service -.->|"applies commands"| node_engine
node_engine -->|"updates"| node_state
node_engine -->|"changes zones"| node_players
node_engine -->|"checks mechanics"| node_card
node_engine -->|"dispatches"| node_commands
node_engine -->|"returns"| node_results
node_fakeengine -->|"updates"| node_state
node_fakeengine -->|"deals and draws"| node_players
node_fakeengine -->|"dispatches"| node_commands
node_fakeengine -->|"returns"| node_results
node_players -->|"owns zones"| node_board
node_players -->|"holds cards"| node_card
node_server -->|"serves card list"| node_cardrepo
node_cardrepo -->|"reads cards"| node_postgres
node_matchrepo -.->|"persists matches"| node_postgres
node_playerrepo -.->|"persists players"| node_postgres
node_player -.->|"exchanges messages"| node_contracts
node_socket -.->|"uses protocol"| node_contracts
node_state -.->|"projects state"| node_stateview

click node_server "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/Program.cs"
click node_socket "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/WebSockets/GameWebSocketHandler.cs"
click node_roommgr "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/Services/RoomManager.cs"
click node_room "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/Models/Room.cs"
click node_matchmgr "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/MatchManager.cs"
click node_match "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Match.cs"
click node_service "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/GameService.cs"
click node_engine "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/GameEngine.cs"
click node_fakeengine "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs"
click node_state "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/GameState.cs"
click node_players "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Player.cs"
click node_board "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Board.cs"
click node_card "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Card.cs"
click node_commands "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Commands/GameCommand.cs"
click node_results "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Results/ApplyResult.cs"
click node_combat "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/CombatRules.cs"
click node_contracts "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Contracts/Messages/ClientMessages.cs"
click node_stateview "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Contracts/State/GameStateView.cs"
click node_restdto "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Contracts/Rest/RestDtos.cs"
click node_cardrepo "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlCardRepository.cs"
click node_matchrepo "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlMatchRepository.cs"
click node_playerrepo "https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlPlayerRepository.cs"

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_server,node_socket toneBlue
class node_roommgr,node_room,node_matchmgr toneAmber
class node_match,node_service,node_engine,node_fakeengine,node_state,node_players,node_board,node_card,node_commands,node_results,node_combat toneMint
class node_cardrepo,node_matchrepo,node_playerrepo,node_postgres toneRose
class node_contracts,node_stateview,node_restdto,node_player toneIndigo
```

## Components

### Server API

- [HTTP/WebSocket Host](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/Program.cs): `MindDuckServer/src/MindDuck.Server/Program.cs`
- [Game Socket Handler](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/WebSockets/GameWebSocketHandler.cs): `MindDuckServer/src/MindDuck.Server/WebSockets/GameWebSocketHandler.cs`

### Rooms and Matches

- [Room Manager](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/Services/RoomManager.cs): `MindDuckServer/src/MindDuck.Server/Services/RoomManager.cs`
- [Room State](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Server/Models/Room.cs): `MindDuckServer/src/MindDuck.Server/Models/Room.cs`
- [Match Manager](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/MatchManager.cs): `MindDuckServer/src/MindDuck.Rules/MatchManager.cs`

### Game Rules

- [Match State](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Match.cs): `MindDuckServer/src/MindDuck.Rules/Models/Match.cs`
- [Game Service](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/GameService.cs): `MindDuckServer/src/MindDuck.Rules/GameService.cs`
- [Game Engine](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/GameEngine.cs): `MindDuckServer/src/MindDuck.Rules/GameEngine.cs`
- [Fake Engine](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs): `MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs`
- [Game State](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/GameState.cs): `MindDuckServer/src/MindDuck.Rules/Models/GameState.cs`
- [Player and Card Model](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Player.cs): `MindDuckServer/src/MindDuck.Rules/Models/Player.cs`
- [Board and Zones](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Board.cs): `MindDuckServer/src/MindDuck.Rules/Models/Board.cs`
- [Card Mechanics](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Models/Card.cs): `MindDuckServer/src/MindDuck.Rules/Models/Card.cs`
- [Player Commands](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Commands/GameCommand.cs): `MindDuckServer/src/MindDuck.Rules/Commands/GameCommand.cs`
- [Apply Results](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/Results/ApplyResult.cs): `MindDuckServer/src/MindDuck.Rules/Results/ApplyResult.cs`
- [Combat Rules](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Rules/CombatRules.cs): `MindDuckServer/src/MindDuck.Rules/CombatRules.cs`

### Card Persistence

- [Card Repository](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlCardRepository.cs): `MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlCardRepository.cs`
- [Match Repository](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlMatchRepository.cs): `MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlMatchRepository.cs`
- [Player Repository](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlPlayerRepository.cs): `MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlPlayerRepository.cs`
- **PostgreSQL**

### Client Protocol

- [Wire Message DTOs](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Contracts/Messages/ClientMessages.cs): `MindDuckServer/src/MindDuck.Contracts/Messages/ClientMessages.cs`
- [State View DTO](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Contracts/State/GameStateView.cs): `MindDuckServer/src/MindDuck.Contracts/State/GameStateView.cs`
- [REST DTOs](https://github.com/vvbocko/mindduck/blob/main/MindDuckServer/src/MindDuck.Contracts/Rest/RestDtos.cs): `MindDuckServer/src/MindDuck.Contracts/Rest/RestDtos.cs`

### Other components

- **Unity Player**

## Connections

- Unity Player → HTTP/WebSocket Host: requests (evidence: `MindDuckServer/src/MindDuck.Server/Program.cs`)
- HTTP/WebSocket Host → Room Manager: creates room (evidence: `MindDuckServer/src/MindDuck.Server/Program.cs`)
- Room Manager → Room State: stores (evidence: `MindDuckServer/src/MindDuck.Server/Services/RoomManager.cs`)
- Unity Player → Game Socket Handler: sends commands
- HTTP/WebSocket Host → Game Socket Handler: dispatches (evidence: `MindDuckServer/src/MindDuck.Server/Program.cs`)
- Game Socket Handler → Room Manager: looks up rooms (evidence: `MindDuckServer/src/MindDuck.Server/WebSockets/GameWebSocketHandler.cs`)
- Match Manager → Match State: stores (evidence: `MindDuckServer/src/MindDuck.Rules/MatchManager.cs`)
- Game Service → Match Manager: manages matches (evidence: `MindDuckServer/src/MindDuck.Rules/GameService.cs`)
- Game Service → Game Engine: applies commands
- Game Engine → Game State: updates (evidence: `MindDuckServer/src/MindDuck.Rules/GameEngine.cs`)
- Game Engine → Player and Card Model: changes zones (evidence: `MindDuckServer/src/MindDuck.Rules/GameEngine.cs`)
- Game Engine → Card Mechanics: checks mechanics (evidence: `MindDuckServer/src/MindDuck.Rules/GameEngine.cs`)
- Game Engine → Player Commands: dispatches (evidence: `MindDuckServer/src/MindDuck.Rules/GameEngine.cs`)
- Game Engine → Apply Results: returns (evidence: `MindDuckServer/src/MindDuck.Rules/GameEngine.cs`)
- Fake Engine → Game State: updates (evidence: `MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs`)
- Fake Engine → Player and Card Model: deals and draws (evidence: `MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs`)
- Fake Engine → Player Commands: dispatches (evidence: `MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs`)
- Fake Engine → Apply Results: returns (evidence: `MindDuckServer/src/MindDuck.Rules/Fakes/FakeGameEngine.cs`)
- Player and Card Model → Board and Zones: owns zones (evidence: `MindDuckServer/src/MindDuck.Rules/Models/Player.cs`)
- Player and Card Model → Card Mechanics: holds cards (evidence: `MindDuckServer/src/MindDuck.Rules/Models/Player.cs`)
- HTTP/WebSocket Host → Card Repository: serves card list (evidence: `MindDuckServer/src/MindDuck.Server/Program.cs`)
- Card Repository → PostgreSQL: reads cards (evidence: `MindDuckServer/src/MindDuck.Persistence/PostgreSql/PostgreSqlCardRepository.cs`)
- Match Repository → PostgreSQL: persists matches
- Player Repository → PostgreSQL: persists players
- Unity Player → Wire Message DTOs: exchanges messages
- Game Socket Handler → Wire Message DTOs: uses protocol
- Game State → State View DTO: projects state
