# drcheeseface/mahc architecture

> Architecture diagram of the GitHub repository drcheeseface/mahc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drcheeseface/mahc
- Repository: https://github.com/drcheeseface/mahc

## Overview

##### Main Components
- CLI Interface – This is where user commands (arguments and flags) enter the system (e.g., from src/main.rs). It handles mode selection (manual mode, normal mode, analyse mode) and file inputs.
- Core Scoring Engine – Modules in the calc directory (src/calc.rs and src/calc/*) implement the core logic. This engine receives validated input (hand details or manual han/fu inputs) and drives the scoring calculations.
- Hand and Tile Representation – Modules for hand (src/hand.rs, src/hand/error.rs) and tiles (src/tile.rs, src/tile_group.rs, src/suit.rs) model the game’s structure. They represent the raw game states (tiles, suits, groups, etc.) and are essential for detecting valid yaku and calculating fu.
- Payment Logic – The module in src/payment.rs calculates and returns payment values once han/fu (score) have been computed.
- Library Interface – The lib.rs file exposes public functions and types of the library, so users can utilize it directly in their Rust projects.
- Additional Supporting Modules – Other modules like src/limit_hand.rs, src/fu.rs, src/score.rs, and src/yaku.rs are used to handle specific scoring rules, limits and validations based on riichi mahjong rules.

##### Relationships and Interactions
- User Input flows from the CLI interface. Depending on the selected mode:
– In Calculator Mode, input parameters like han and fu are forwarded directly to the scoring and payment modules.
– In Normal Mode, the CLI passes the tile information and any additional flags to the hand/tile parser, then forwards the constructed Hand object to the scoring engine.
- The parsed hand or tiles are used by the scoring engine, which collaborates with the yaku and fu modules to determine valid scoring patterns.
- Once the score is established, the payment module computes point values based on whether the player is dealer or non-dealer.
- Finally, the results are serialized or printed (optionally as JSON) back through the CLI.

##### Architectural Patterns and Design Principles
- Modular Design: The project is organized into clear, modular components (e.g., calc, hand, tile, payment) that each serve specific roles.
- Separation of Concerns: There is a clear distinction between the core scoring logic and the CLI presentation—making the library reusable.
- Domain-Specific Abstraction: The code models Riichi Mahjong concepts directly (tiles, suits, yaku, etc.), which simplifies reasoning about the game logic.
- Error Handling: There are error modules within subdirectories (e.g., src/calc/error.rs, src/hand/error.rs) suggesting a separation of error concerns.

##### Relevant Technologies and Frameworks
- Rust: The entire project is built in Rust, and the Cargo.toml file indicates dependency management.
- GitHub Actions: The .github/workflows directory (with rust.yml) suggests automated CI/CD.
- CLI Parsing: Likely uses a CLI argument parser (such as clap or structopt) though it is not explicitly shown, it is implied by the mode-specific command usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Interface"]:::cli
        Parse["CLI Parsing (Mode Selection)"]:::cli
        Output["Output Formatter"]:::cli
    end
    CLI --> Parse

    %% Mode Selection
    Parse -->|"calculator"| CalcMode["Calculator Mode Input"]:::cli
    Parse -->|"normal"| NormalMode["Normal Mode Input"]:::cli
    Parse -->|"analyse"| AnalyseMode["Analyse Mode Input"]:::cli

    %% Domain (Hand & Tile) Layer
    subgraph "Hand & Tile Modules"
        Hand["Hand"]:::domain
        HandErr["Hand Error Handling"]:::domain
        Tile["Tile"]:::domain
        TileGroup["Tile Group"]:::domain
        Suit["Suit"]:::domain
    end

    %% Scoring Engine Layer
    subgraph "Scoring Engine"
        Core["Core Scoring Engine"]:::scoring
        CalcErr["Calc Error Handling"]:::scoring
        CalcUtils["Calc Utils"]:::scoring
    end

    %% Additional Modules for Scoring Rules and Validations
    subgraph "Additional Modules"
        FuCalc["Fu Calculation"]:::add
        ScoreComp["Score Computation"]:::add
        YakuDetect["Yaku Detection"]:::add
        LimitHand["Limit Hand Handling"]:::add
    end

    %% Payment Module and Library Interface
    Payment["Payment Logic"]:::payment
    Library["Library Interface"]:::library

    %% Data Flow Connections
    %% From CLI inputs to processing
    CalcMode --> Core
    NormalMode --> Hand
    AnalyseMode --> Hand

    %% Hand & Tile Modules provide input to Core Scoring Engine
    Hand -- "parsed data" --> Core
    Tile -- "tile data" --> Core
    TileGroup -- "grouped tiles" --> Core
    Suit -- "suit info" --> Core

    %% Core Scoring Engine internal details
    Core --> CalcErr
    Core --> CalcUtils

    %% Core interacts with additional scoring modules
    Core --> FuCalc
    Core --> ScoreComp
    Core --> YakuDetect
    Core --> LimitHand

    %% Core scoring output flows to Payment Logic
    Core --> Payment

    %% Library Interface provides access to core modules
    Library --- Core
    Library --- Hand
    Library --- Payment

    %% Final output flows back to CLI Output Formatter
    Payment --> Output

    %% Styles
    classDef cli fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef scoring fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef domain fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef payment fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef library fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef add fill:#FFA07A,stroke:#000,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/drcheeseface/mahc/blob/main/src/main.rs"
    click Core "https://github.com/drcheeseface/mahc/blob/main/src/calc.rs"
    click CalcErr "https://github.com/drcheeseface/mahc/blob/main/src/calc/error.rs"
    click CalcUtils "https://github.com/drcheeseface/mahc/blob/main/src/calc/utils.rs"
    click Hand "https://github.com/drcheeseface/mahc/blob/main/src/hand.rs"
    click HandErr "https://github.com/drcheeseface/mahc/blob/main/src/hand/error.rs"
    click Tile "https://github.com/drcheeseface/mahc/blob/main/src/tile.rs"
    click TileGroup "https://github.com/drcheeseface/mahc/blob/main/src/tile_group.rs"
    click Suit "https://github.com/drcheeseface/mahc/blob/main/src/suit.rs"
    click Payment "https://github.com/drcheeseface/mahc/blob/main/src/payment.rs"
    click Library "https://github.com/drcheeseface/mahc/blob/main/src/lib.rs"
    click FuCalc "https://github.com/drcheeseface/mahc/blob/main/src/fu.rs"
    click ScoreComp "https://github.com/drcheeseface/mahc/blob/main/src/score.rs"
    click YakuDetect "https://github.com/drcheeseface/mahc/blob/main/src/yaku.rs"
    click LimitHand "https://github.com/drcheeseface/mahc/blob/main/src/limit_hand.rs"
```
