# herochessvn/herochessbackend architecture

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

- Interactive diagram: https://gitdiagram.com/herochessvn/herochessbackend
- Repository: https://github.com/herochessvn/herochessbackend

## Overview

HeroChess is a server-authoritative Xiangqi game with hero lineups, matchmaking, persistent matches, special skills, and shop/profile features. The principal workflow is matchmaking → lineup selection and freezing → match commands → rule resolution and settlement, with saved state and realtime updates. The graph preserves documented API capabilities and background match operations, but several controller and service implementations were not excerpted; dashed edges mark relationships whose exact runtime calls could not be verified.

Main entry points: [`HeroChess.Api/Program.cs`](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Program.cs) (REST API), [`HeroChess.Api/Services/MatchCommandService.cs`](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchCommandService.cs) (Match commands), [`HeroChess.Api/Data/AppDbContext.cs`](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Data/AppDbContext.cs) (PostgreSQL data), [`HeroChess.Api/Services/MatchmakingService.cs`](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchmakingService.cs) (Matchmaking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and accounts"]
  node_api["REST API<br/>[Program.cs]"]
  node_auth["Account policies<br/>[AccountPolicies.cs]"]
  node_catalog["Catalog"]
  node_profile["Profile and shop"]
  node_bootstrap["Database bootstrap"]
end

subgraph group_setup["Game setup"]
  node_matchmaking["Matchmaking"]
  node_lineups["Lineup management<br/>[LineupService.cs]"]
  node_selection["Match selection"]
end

subgraph group_match["Match runtime"]
  node_commands["Match commands"]
  node_reads["Match reads"]
  node_realtime["Realtime hub"]
  node_workers["Match workers"]
  node_settlement["Settlement"]
end

subgraph group_rules["Rules engine"]
  node_rules["Xiangqi rules"]
  node_lifecycle["Turn lifecycle<br/>[TurnLifecycle.cs]"]
  node_skills["Skill dispatch"]
  node_skillhandlers["Skill handlers"]
  node_effects["Effect model<br/>[EffectFactory.cs]"]
end

node_player(("Player"))
node_database[("PostgreSQL data<br/>[AppDbContext.cs]")]

node_player -.->|"uses API"| node_api
node_api -->|"configures"| node_auth
node_api -->|"registers"| node_matchmaking
node_api -->|"starts workers"| node_workers
node_api -->|"starts bootstrap"| node_bootstrap
node_api -.->|"routes requests"| node_catalog
node_api -.->|"routes requests"| node_profile
node_api -.->|"routes requests"| node_lineups
node_api -.->|"routes requests"| node_selection
node_api -.->|"routes requests"| node_commands
node_matchmaking -->|"writes matches"| node_database
node_matchmaking -.->|"checks version"| node_catalog
node_lineups -.->|"reads and writes"| node_database
node_selection -->|"loads lineups"| node_database
node_selection -->|"validates lineup"| node_lineups
node_commands -->|"saves actions"| node_database
node_commands -.->|"resolves moves"| node_rules
node_commands -.->|"applies lifecycle"| node_lifecycle
node_commands -.->|"dispatches skills"| node_skills
node_commands -.->|"completes matches"| node_settlement
node_commands -.->|"broadcasts events"| node_realtime
node_reads -.->|"reads snapshots"| node_database
node_workers -.->|"submits bot turns"| node_commands
node_workers -.->|"recovers matches"| node_database
node_skills -.->|"dispatches handlers"| node_skillhandlers
node_skillhandlers -->|"creates effects"| node_effects
node_bootstrap -->|"initializes"| node_database

click node_api "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Program.cs"
click node_auth "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Auth/AccountPolicies.cs"
click node_catalog "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Controllers/CatalogController.cs"
click node_profile "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Controllers/ProfileController.cs"
click node_matchmaking "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchmakingService.cs"
click node_lineups "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/LineupService.cs"
click node_selection "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchSelectionService.cs"
click node_commands "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchCommandService.cs"
click node_reads "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchReadService.cs"
click node_realtime "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchConnectionHub.cs"
click node_workers "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchRecoveryHostedService.cs"
click node_settlement "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/SettlementService.cs"
click node_rules "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/XiangqiRulesEngine.cs"
click node_lifecycle "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/TurnLifecycle.cs"
click node_skills "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/Skills/CommandSkillDispatcher.cs"
click node_skillhandlers "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/Skills/VanCocTranGiangHandler.cs"
click node_effects "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/Effects/EffectFactory.cs"
click node_database "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Data/AppDbContext.cs"
click node_bootstrap "https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Data/Bootstrap/DatabaseBootstrapHostedService.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_api,node_auth,node_catalog,node_profile,node_bootstrap toneBlue
class node_matchmaking,node_lineups,node_selection,node_database toneAmber
class node_commands,node_reads,node_realtime,node_workers,node_settlement toneMint
class node_rules,node_lifecycle,node_skills,node_skillhandlers,node_effects toneRose
class node_player toneIndigo
```

## Components

### API and accounts

- [REST API](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Program.cs): `HeroChess.Api/Program.cs`
- [Account policies](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Auth/AccountPolicies.cs): `HeroChess.Api/Auth/AccountPolicies.cs`
- [Catalog](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Controllers/CatalogController.cs): `HeroChess.Api/Controllers/CatalogController.cs`
- [Profile and shop](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Controllers/ProfileController.cs): `HeroChess.Api/Controllers/ProfileController.cs`
- [Database bootstrap](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Data/Bootstrap/DatabaseBootstrapHostedService.cs): `HeroChess.Api/Data/Bootstrap/DatabaseBootstrapHostedService.cs`

### Game setup

- [Matchmaking](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchmakingService.cs): `HeroChess.Api/Services/MatchmakingService.cs`
- [Lineup management](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/LineupService.cs): `HeroChess.Api/Services/LineupService.cs`
- [Match selection](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchSelectionService.cs): `HeroChess.Api/Services/MatchSelectionService.cs`

### Match runtime

- [Match commands](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchCommandService.cs): `HeroChess.Api/Services/MatchCommandService.cs`
- [Match reads](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchReadService.cs): `HeroChess.Api/Services/MatchReadService.cs`
- [Realtime hub](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchConnectionHub.cs): `HeroChess.Api/Services/MatchConnectionHub.cs`
- [Match workers](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/MatchRecoveryHostedService.cs): `HeroChess.Api/Services/MatchRecoveryHostedService.cs`
- [Settlement](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Services/SettlementService.cs): `HeroChess.Api/Services/SettlementService.cs`

### Rules engine

- [Xiangqi rules](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/XiangqiRulesEngine.cs): `HeroChess.Rules/XiangqiRulesEngine.cs`
- [Turn lifecycle](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/TurnLifecycle.cs): `HeroChess.Rules/TurnLifecycle.cs`
- [Skill dispatch](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/Skills/CommandSkillDispatcher.cs): `HeroChess.Rules/Skills/CommandSkillDispatcher.cs`
- [Skill handlers](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/Skills/VanCocTranGiangHandler.cs): `HeroChess.Rules/Skills/VanCocTranGiangHandler.cs`
- [Effect model](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Rules/Effects/EffectFactory.cs): `HeroChess.Rules/Effects/EffectFactory.cs`

### Other components

- **Player**
- [PostgreSQL data](https://github.com/herochessvn/herochessbackend/blob/master/HeroChess.Api/Data/AppDbContext.cs): `HeroChess.Api/Data/AppDbContext.cs`

## Connections

- Player → REST API: uses API
- REST API → Account policies: configures (evidence: `HeroChess.Api/Program.cs`)
- REST API → Matchmaking: registers (evidence: `HeroChess.Api/Program.cs`)
- REST API → Match workers: starts workers (evidence: `HeroChess.Api/Program.cs`)
- REST API → Database bootstrap: starts bootstrap (evidence: `HeroChess.Api/Program.cs`)
- REST API → Catalog: routes requests
- REST API → Profile and shop: routes requests
- REST API → Lineup management: routes requests (evidence: `HeroChess.Api/Program.cs`)
- REST API → Match selection: routes requests (evidence: `HeroChess.Api/Program.cs`)
- REST API → Match commands: routes requests (evidence: `HeroChess.Api/Program.cs`)
- Matchmaking → PostgreSQL data: writes matches (evidence: `HeroChess.Api/Services/MatchmakingService.cs`)
- Matchmaking → Catalog: checks version
- Lineup management → PostgreSQL data: reads and writes (evidence: `HeroChess.Api/Services/LineupService.cs`)
- Match selection → PostgreSQL data: loads lineups (evidence: `HeroChess.Api/Services/MatchSelectionService.cs`)
- Match selection → Lineup management: validates lineup (evidence: `HeroChess.Api/Services/MatchSelectionService.cs`)
- Match commands → PostgreSQL data: saves actions (evidence: `HeroChess.Api/Services/MatchCommandService.cs`)
- Match commands → Xiangqi rules: resolves moves (evidence: `HeroChess.Api/Services/MatchCommandService.cs`)
- Match commands → Turn lifecycle: applies lifecycle (evidence: `HeroChess.Api/Services/MatchCommandService.cs`)
- Match commands → Skill dispatch: dispatches skills (evidence: `HeroChess.Api/Services/MatchCommandService.cs`)
- Match commands → Settlement: completes matches (evidence: `HeroChess.Api/Services/MatchCommandService.cs`)
- Match commands → Realtime hub: broadcasts events (evidence: `HeroChess.Api/Services/MatchCommandService.cs`)
- Match reads → PostgreSQL data: reads snapshots (evidence: `HeroChess.Api/Services/MatchReadService.cs`)
- Match workers → Match commands: submits bot turns
- Match workers → PostgreSQL data: recovers matches
- Skill dispatch → Skill handlers: dispatches handlers
- Skill handlers → Effect model: creates effects (evidence: `HeroChess.Rules/Skills/VanCocTranGiangHandler.cs`)
- Database bootstrap → PostgreSQL data: initializes (evidence: `HeroChess.Api/Data/Bootstrap/DatabaseBootstrapHostedService.cs`)
