# duma520/mahjong_calculator architecture

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

## Overview

Mahjong Calculator is a Chinese Official Mahjong scoring tool. Players enter concealed tiles, melds, winning-tile circumstances, and winds in the desktop or Web interface; the app analyzes waits and scores a completed hand, reporting fan totals and qualifying patterns. The core also exposes a Python/JSON-facing interface and command-line entry point, while the Web server enables browser and LAN access. README capabilities guide the map; source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`mahjong_core.py`](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py) (Core API), [`Mahjong_Calculator.py`](https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py) (Desktop App), [`mahjong_api.py`](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py) (JSON Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_desktop_app["Desktop App"]
  node_hand_input["Hand Input"]
  node_wait_display["Wait Analysis"]
  node_score_display["Score Results"]
  node_fan_reference["Fan Reference"]
end

subgraph group_service["Web Service"]
  node_web_server["HTTP Server<br/>[mahjong_api.py]"]
  node_web_client["Web Interface<br/>[mahjong_api.py]"]
  node_api_routes["JSON Routes<br/>[mahjong_api.py]"]
  node_access_control["Token Access<br/>[mahjong_api.py]"]
end

subgraph group_engine["Scoring Engine"]
  node_engine_api["Core API<br/>[mahjong_core.py]"]
  node_hand_decomposition["Hand Decomposition<br/>[mahjong_core.py]"]
  node_fan_detection["Fan Detection<br/>[mahjong_core.py]"]
  node_exclusion_scoring["Exclusions and Score<br/>[mahjong_core.py]"]
  node_wait_calculation["Wait Calculation<br/>[mahjong_core.py]"]
  node_fan_catalog["Fan Catalog<br/>[mahjong_core.py]"]
end

subgraph group_interfaces["Programmatic Access"]
  node_cli["Command Line<br/>[mahjong_core.py]"]
end

node_desktop_user(("Desktop Player"))
node_web_user(("Browser Player"))
node_developer(("API Consumer"))

node_desktop_user -->|"uses"| node_desktop_app
node_desktop_app -->|"provides"| node_hand_input
node_hand_input -->|"submits hand"| node_engine_api
node_engine_api -->|"analyzes waits"| node_wait_calculation
node_engine_api -->|"decomposes hand"| node_hand_decomposition
node_hand_decomposition -->|"checks patterns"| node_fan_detection
node_fan_detection -->|"applies scoring"| node_exclusion_scoring
node_wait_calculation -->|"returns waits"| node_wait_display
node_exclusion_scoring -->|"returns score"| node_score_display
node_desktop_app -->|"shows reference"| node_fan_reference
node_fan_catalog -->|"supplies definitions"| node_fan_reference
node_desktop_app -->|"starts service"| node_web_server
node_web_user -->|"connects"| node_web_server
node_web_server -->|"serves page"| node_web_client
node_web_client -->|"submits requests"| node_api_routes
node_api_routes -->|"checks access"| node_access_control
node_api_routes -->|"calls scoring"| node_engine_api
node_engine_api -->|"returns result"| node_api_routes
node_developer -->|"calls directly"| node_engine_api
node_developer -->|"runs"| node_cli
node_cli -->|"invokes"| node_engine_api

click node_desktop_app "https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py"
click node_hand_input "https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py"
click node_wait_display "https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py"
click node_score_display "https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py"
click node_fan_reference "https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py"
click node_web_server "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py"
click node_web_client "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py"
click node_api_routes "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py"
click node_access_control "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py"
click node_engine_api "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py"
click node_hand_decomposition "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py"
click node_fan_detection "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py"
click node_exclusion_scoring "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py"
click node_wait_calculation "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py"
click node_fan_catalog "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py"
click node_cli "https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.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_desktop_app,node_hand_input,node_wait_display,node_score_display,node_fan_reference,node_web_user toneBlue
class node_web_server,node_web_client,node_api_routes,node_access_control toneAmber
class node_engine_api,node_hand_decomposition,node_fan_detection,node_exclusion_scoring,node_wait_calculation,node_fan_catalog,node_developer toneMint
class node_cli toneRose
class node_desktop_user toneIndigo
```

## Components

### User Interfaces

- [Desktop App](https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py): `Mahjong_Calculator.py`
- [Hand Input](https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py): `Mahjong_Calculator.py`
- [Wait Analysis](https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py): `Mahjong_Calculator.py`
- [Score Results](https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py): `Mahjong_Calculator.py`
- [Fan Reference](https://github.com/duma520/mahjong_calculator/blob/main/Mahjong_Calculator.py): `Mahjong_Calculator.py`

### Web Service

- [HTTP Server](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py): `mahjong_api.py`
- [Web Interface](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py): `mahjong_api.py`
- [JSON Routes](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py): `mahjong_api.py`
- [Token Access](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_api.py): `mahjong_api.py`

### Scoring Engine

- [Core API](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py): `mahjong_core.py`
- [Hand Decomposition](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py): `mahjong_core.py`
- [Fan Detection](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py): `mahjong_core.py`
- [Exclusions and Score](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py): `mahjong_core.py`
- [Wait Calculation](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py): `mahjong_core.py`
- [Fan Catalog](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py): `mahjong_core.py`

### Programmatic Access

- [Command Line](https://github.com/duma520/mahjong_calculator/blob/main/mahjong_core.py): `mahjong_core.py`

### Other components

- **Desktop Player**
- **Browser Player**
- **API Consumer**

## Connections

- Desktop Player → Desktop App: uses
- Desktop App → Hand Input: provides
- Hand Input → Core API: submits hand
- Core API → Wait Calculation: analyzes waits
- Core API → Hand Decomposition: decomposes hand
- Hand Decomposition → Fan Detection: checks patterns
- Fan Detection → Exclusions and Score: applies scoring
- Wait Calculation → Wait Analysis: returns waits
- Exclusions and Score → Score Results: returns score
- Desktop App → Fan Reference: shows reference
- Fan Catalog → Fan Reference: supplies definitions
- Desktop App → HTTP Server: starts service
- Browser Player → HTTP Server: connects
- HTTP Server → Web Interface: serves page
- Web Interface → JSON Routes: submits requests
- JSON Routes → Token Access: checks access
- JSON Routes → Core API: calls scoring
- Core API → JSON Routes: returns result
- API Consumer → Core API: calls directly
- API Consumer → Command Line: runs
- Command Line → Core API: invokes