# jordan-diaz-eng/lightweightriichimahjong architecture

> Architecture diagram of the GitHub repository jordan-diaz-eng/lightweightriichimahjong, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jordan-diaz-eng/lightweightriichimahjong
- Repository: https://github.com/jordan-diaz-eng/lightweightriichimahjong

## Overview

LightweightRiichiMahjong is a C++ riichi mahjong rules engine. Its principal workflow is to initialize and deal a hand, present legal actions, apply player decisions through turn and call windows, and produce a hand result; clients can also inspect redacted event observations. The public model adds hand parsing, shanten/ukeire analysis, and scoring. The README is minimal, so capability detail comes from the sampled engine and model sources; unsampled subsystem wiring is omitted.

Main entry points: [`LRMahjong/src/LRMahjong/Engine.cpp`](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Engine.cpp) (Hand engine), [`ConsoleApp/src/Application.cpp`](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/ConsoleApp/src/Application.cpp) (Console example), [`LRMahjong/src/LRMahjong/Model/LegalActions.cpp`](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/LegalActions.cpp) (Legal actions), [`LRMahjong/src/LRMahjong/Model/Score.cpp`](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Score.cpp) (Hand scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Hand runtime"]
  node_engine["Hand engine<br/>[Engine.cpp]"]
  node_rng["Random generator<br/>[RNG.h]"]
  node_result["Hand result<br/>[Score.h]"]
end

subgraph group_rules["Rules and analysis"]
  node_legal["Legal actions<br/>[LegalActions.cpp]"]
  node_rulescfg["Rule presets<br/>[Rules.h]"]
  node_win["Win checking<br/>[WinCheck.cpp]"]
  node_score["Hand scoring<br/>[Score.cpp]"]
  node_shanten["Shanten and ukeire<br/>[Shanten.cpp]"]
end

subgraph group_state["State and visibility"]
  node_state["Game state<br/>[GameState.cpp]"]
  node_player["Player hand<br/>[Player.cpp]"]
  node_hand["Hand operations<br/>[Hand.cpp]"]
  node_tile["Tile model<br/>[Tile.cpp]"]
  node_observation["Event observations<br/>[Observation.cpp]"]
end

subgraph group_client["Client interface"]
  node_app["Console example<br/>[Application.cpp]"]
  node_parse["Hand parsing<br/>[HandParse.cpp]"]
end

node_user(("Library consumer"))

node_user -->|"runs example"| node_app
node_user -->|"uses library"| node_engine
node_app -->|"starts and steps"| node_engine
node_app -->|"requests actions"| node_legal
node_app -->|"queries waits"| node_shanten
node_app -->|"requests score"| node_score
node_app -->|"parses hand"| node_parse
node_engine -->|"validates action"| node_legal
node_engine -->|"updates state"| node_state
node_engine -->|"shuffles wall"| node_rng
node_engine -->|"records events"| node_observation
node_engine -->|"sets outcome"| node_result
node_legal -->|"checks yaku"| node_score
node_legal -->|"checks readiness"| node_shanten
node_legal -->|"checks wins"| node_win
node_score -->|"decomposes hand"| node_win
node_observation -->|"reconstructs belief"| node_shanten
node_state -->|"holds players"| node_player
node_player -->|"maintains tiles"| node_hand
node_hand -->|"uses tile counts"| node_tile
node_engine -->|"uses rules"| node_rulescfg

click node_app "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/ConsoleApp/src/Application.cpp"
click node_engine "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Engine.cpp"
click node_legal "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/LegalActions.cpp"
click node_rulescfg "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Rules.h"
click node_win "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/WinCheck.cpp"
click node_score "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Score.cpp"
click node_shanten "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Shanten.cpp"
click node_parse "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/HandParse.cpp"
click node_state "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/GameState.cpp"
click node_player "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Player.cpp"
click node_hand "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Hand.cpp"
click node_tile "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Tile.cpp"
click node_observation "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Observation.cpp"
click node_rng "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/RNG.h"
click node_result "https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Score.h"

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_engine,node_rng,node_result toneBlue
class node_legal,node_rulescfg,node_win,node_score,node_shanten toneAmber
class node_state,node_player,node_hand,node_tile,node_observation toneMint
class node_app,node_parse toneRose
class node_user toneIndigo
```

## Components

### Hand runtime

- [Hand engine](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Engine.cpp): `LRMahjong/src/LRMahjong/Engine.cpp`
- [Random generator](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/RNG.h): `LRMahjong/src/LRMahjong/RNG.h`
- [Hand result](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Score.h): `LRMahjong/src/LRMahjong/Model/Score.h`

### Rules and analysis

- [Legal actions](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/LegalActions.cpp): `LRMahjong/src/LRMahjong/Model/LegalActions.cpp`
- [Rule presets](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Rules.h): `LRMahjong/src/LRMahjong/Model/Rules.h`
- [Win checking](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/WinCheck.cpp): `LRMahjong/src/LRMahjong/Model/WinCheck.cpp`
- [Hand scoring](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Score.cpp): `LRMahjong/src/LRMahjong/Model/Score.cpp`
- [Shanten and ukeire](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Shanten.cpp): `LRMahjong/src/LRMahjong/Model/Shanten.cpp`

### State and visibility

- [Game state](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/GameState.cpp): `LRMahjong/src/LRMahjong/Model/GameState.cpp`
- [Player hand](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Player.cpp): `LRMahjong/src/LRMahjong/Model/Player.cpp`
- [Hand operations](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Hand.cpp): `LRMahjong/src/LRMahjong/Model/Hand.cpp`
- [Tile model](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Tile.cpp): `LRMahjong/src/LRMahjong/Model/Tile.cpp`
- [Event observations](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/Observation.cpp): `LRMahjong/src/LRMahjong/Model/Observation.cpp`

### Client interface

- [Console example](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/ConsoleApp/src/Application.cpp): `ConsoleApp/src/Application.cpp`
- [Hand parsing](https://github.com/jordan-diaz-eng/lightweightriichimahjong/blob/main/LRMahjong/src/LRMahjong/Model/HandParse.cpp): `LRMahjong/src/LRMahjong/Model/HandParse.cpp`

### Other components

- **Library consumer**

## Connections

- Library consumer → Console example: runs example
- Library consumer → Hand engine: uses library
- Console example → Hand engine: starts and steps
- Console example → Legal actions: requests actions
- Console example → Shanten and ukeire: queries waits
- Console example → Hand scoring: requests score
- Console example → Hand parsing: parses hand
- Hand engine → Legal actions: validates action
- Hand engine → Game state: updates state
- Hand engine → Random generator: shuffles wall
- Hand engine → Event observations: records events
- Hand engine → Hand result: sets outcome
- Legal actions → Hand scoring: checks yaku
- Legal actions → Shanten and ukeire: checks readiness
- Legal actions → Win checking: checks wins
- Hand scoring → Win checking: decomposes hand
- Event observations → Shanten and ukeire: reconstructs belief
- Game state → Player hand: holds players
- Player hand → Hand operations: maintains tiles
- Hand operations → Tile model: uses tile counts
- Hand engine → Rule presets: uses rules