# cryolite/kanachan architecture

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

- Interactive diagram: https://gitdiagram.com/cryolite/kanachan
- Repository: https://github.com/cryolite/kanachan

## Overview

##### Main Components
- Data Preprocessing and Annotation:
– The annotation tool lives in src/annotation and the bin/annotate4rl directory. These components extract decision-making points from raw game records (collected externally) and convert them into learning annotations.
– The paishan module (src/paishan) restores the full tile wall from game records.
– The xiangting module (src/xiangting) computes shanten (xiang ting) values by constructing a LOUDS-based trie.
- Simulation Engine:
– The simulation library in src/simulation (and its Python wrapper in kanachan/simulation) implements the Mahjong game logic accurately. This code is used to validate annotations (with the test/annotation_vs_simulation framework) and is also used as part of the game play simulation during training.
- AI Model Training:
– The training pipelines are implemented in the kanachan/training directory. There are several submodules (aiayn, bert, cql, ilql, iql) that represent different training methodologies/phases which together form the curriculum fine-tuning process.
– These components are built on PyTorch and use the encoder–decoder split where the encoder is shared across training phases while the decoder is replaced.
- Auxiliary and Infrastructure Components:
– The prerequisites directory holds tools and dependencies (available as Docker images) needed by developers.
– The mjai.app directory provides an application layer (with Dockerfiles and scripts) that likely serves as a front-end or an integration point for real-game scenarios.
– Configuration and build files (CMakeLists.txt, setup.py, pyproject.toml, etc.) and container definitions (.devcontainer, multiple Dockerfiles) orchestrate building, testing, and deployment in a containerized environment.

##### Relationships and Interactions
- Data Flow:
- Game records (collected externally) are input to the annotation components (src/annotation and/or bin/annotate4rl). The output is a set of annotations capturing decision points.
- These annotations are also validated using the simulation engine (test/annotation_vs_simulation checks consistency).
- Model Training:
- The annotated data from the preprocessing stage goes into the training pipelines in kanachan/training.
- Intermediate models (shared encoders) are refined via curriculum fine-tuning across the various training phases (aiayn, bert, cql, ilql, iql).
- Simulation and Verification:
- The simulation engine (src/simulation) provides a sandbox to test the game logic by running simulated rounds and comparing with annotation outputs.
- Containerization and Deployment:
- Dockerfiles in different subdirectories (e.g., in bin/annotate4rl, kanachan/simulation, prerequisites, mjai.app, etc.) indicate that each major component is containerized. This informs infrastructural boundaries and deployment units.

##### Architectural Patterns and Design Principles
- Modularization:
- Each major functional area (annotation, simulation, training) is split into separate directories with clear responsibilities.
- Separation of Concerns:
- The preprocessing (C++ tools) is decoupled from the training processes (Python/PyTorch), and the simulation engine (both C++ and Python) works independently for testing game logic.
- Containerization:
- The presence of Dockerfiles and development containers (.devcontainer) suggests that each component may be developed, tested, and deployed independently.
- Curriculum Learning:
- The training modules demonstrate a two-part design, with the encoder capturing general Mahjong knowledge and the decoder tailored to different objectives (e.g., imitation vs. score maximization).
- Interoperability:
- The design ensures that C++ tools and Python libraries can interact, for example via wrappers or shared data formats (annotations).

##### Relevant Technologies, Frameworks, and Libraries
- C++ components managed via CMake (CMakeLists.txt in various directories).
- Python modules and training code using PyTorch (referenced in the README).
- Container orchestration using Docker (.devcontainer, Dockerfiles).
- Trie data structures implemented via LOUDS (referenced for xiangting).
- Testing with GoogleTest (visible under prerequisites/googletest) for C++ modules.
- Continuous integration/development environment is emphasized via configuration and build scripts.

- Labels that mention key technologies (e.g., CMake for building C++, PyTorch for training, Docker for deployment) and brief notes about each module’s function.
- That components like curriculum fine-tuning and the encoder–decoder reuse strategy in the training layer are clearly highlighted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input
    INPUT["Raw Game Records (External)"]:::external

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        A1["Annotation Tool (src/annotation)"]:::cpp
        A2["Annotation Tool Binary (bin/annotate4rl)"]:::cpp
        PA["Tile Wall Restoration (src/paishan)"]:::cpp
        X1["Xiangting Calculator (src/xiangting)"]:::cpp
        X2["Xiangting Calculator (mjai.app/xiangting_calculator)"]:::cpp
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        S1["C++ Core Simulation (src/simulation)"]:::cpp
        S2["Python Simulation Wrapper (kanachan/simulation)"]:::py
        S3["Simulation Validation (test/annotation_vs_simulation)"]:::cpp
    end

    %% Training Layer
    subgraph "Training Layer"
        TP["Training Pipelines (kanachan/training)"]:::py
        T1["aiayn Module (kanachan/training/aiayn)"]:::py
        T2["bert Module (kanachan/training/bert)"]:::py
        T3["cql Module (kanachan/training/cql)"]:::py
        T4["ilql Module (kanachan/training/ilql)"]:::py
        T5["iql Module (kanachan/training/iql)"]:::py
    end

    %% Application / Interface Layer
    MJAI["MJAI Interface (mjai.app)"]:::container

    %% Auxiliary / Infrastructure Layer
    Infra["Prerequisites & Container Setup (prerequisites, .devcontainer)"]:::container

    %% Data Flow Connections
    INPUT --> A1
    INPUT --> A2
    INPUT --> PA

    %% Annotation output flows to Simulation Validation and Training
    A1 --> S3
    A2 --> S3
    A1 --> TP
    A2 --> TP

    %% Xiangting components connection
    X1 <--> X2

    %% Simulation Layer connections
    S3 --> S1
    S3 --> S2

    %% Training Pipeline branching
    TP --> T1
    TP --> T2
    TP --> T3
    TP --> T4
    TP --> T5

    %% Indicate shared encoder reuse from aiayn to other training phases
    T1 -->|"shared_encoder"| T2
    T1 -->|"shared_encoder"| T3
    T1 -->|"shared_encoder"| T4
    T1 -->|"shared_encoder"| T5

    %% Deployment of trained models to Application Interface
    TP -->|"deploy_model"| MJAI

    %% Containerization / Infrastructure relationships (dotted lines)
    Infra -.-> A1
    Infra -.-> A2
    Infra -.-> PA
    Infra -.-> X1
    Infra -.-> S1
    Infra -.-> TP
    Infra -.-> MJAI

    %% Click Events
    click A1 "https://github.com/cryolite/kanachan/tree/main/src/annotation"
    click A2 "https://github.com/cryolite/kanachan/tree/main/bin/annotate4rl"
    click PA "https://github.com/cryolite/kanachan/tree/main/src/paishan"
    click X1 "https://github.com/cryolite/kanachan/tree/main/src/xiangting"
    click X2 "https://github.com/cryolite/kanachan/tree/main/mjai.app/xiangting_calculator"
    click S1 "https://github.com/cryolite/kanachan/tree/main/src/simulation"
    click S2 "https://github.com/cryolite/kanachan/tree/main/kanachan/simulation"
    click S3 "https://github.com/cryolite/kanachan/tree/main/test/annotation_vs_simulation"
    click TP "https://github.com/cryolite/kanachan/tree/main/kanachan/training"
    click T1 "https://github.com/cryolite/kanachan/tree/main/kanachan/training/aiayn"
    click T2 "https://github.com/cryolite/kanachan/tree/main/kanachan/training/bert"
    click T3 "https://github.com/cryolite/kanachan/tree/main/kanachan/training/cql"
    click T4 "https://github.com/cryolite/kanachan/tree/main/kanachan/training/ilql"
    click T5 "https://github.com/cryolite/kanachan/tree/main/kanachan/training/iql"
    click MJAI "https://github.com/cryolite/kanachan/blob/main/mjai.app"
    click Infra "https://github.com/cryolite/kanachan/tree/main/prerequisites"

    %% Styles
    classDef cpp fill:#F08080,stroke:#333,stroke-width:2px;
    classDef py fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef container fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
