# linxin8/chinese-chess architecture

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

- Interactive diagram: https://gitdiagram.com/linxin8/chinese-chess
- Repository: https://github.com/linxin8/chinese-chess

## Overview

##### Project type and purpose
- This is a desktop “full‑stack” application (Windows Presentation Foundation on .NET) that integrates with a native C++ AI engine implementing minimax/α‑β/Negamax search and heuristic evaluation for Chinese Chess.
- The README confirms its focus: “基于极大极小算法的中国象棋程序” (a Chinese Chess program based on minimax).

##### File structure
- Top‐level solution (WpfApp.sln) contains two projects:
- WpfApp (C# / XAML): the UI and game controller
- DecisionTree (C++ .vcxproj): native chess‑AI engine
- WpfApp folder:
- App.xaml + MainWindow.xaml + code‑behind → UI layer
- Chess.cs, ChessBoard.xaml.cs, ChessGame.csproj → game model & controller
- GlobalRule.cs, LogicMap.cs → rule engine, board representation
- UserControl1.xaml → custom WPF control
- DecisionTree folder:
- bitboard.cpp/h, bittree.cpp/h → core data structures for board & game tree
- dllfunction.cpp/h → exported functions for P/Invoke

##### Key insights from README
- The engine implements: search tree abstraction, minimax, α‑β pruning, NegaMax, quiescent search, null‑window search, null‑move, move‐ordering heuristics, Zobrist hashing.
- No external services; all computation is in‐process.

##### Main components & interactions
a. Components:
– UI Layer (WPF Frontend)
– Game Controller / Model (C# classes: ChessGame, GlobalRule, LogicMap)
– Native AI Engine (C++ DLL: DecisionTree)
– Data Structures (Bitboard, BitTree)
– Cache/History Tables & Zobrist Hash Table
b. Interactions:
1. User clicks on board (MainWindow) → triggers ChessGame move request
2. ChessGame calls into DecisionTree via P/Invoke (dllfunction)
3. DecisionTree builds search tree (using BitBoard/BitTree), runs minimax/α‑β, returns best move
4. ChessGame applies move → UI updates ChessBoard
5. During engine run, history tables & Zobrist hash serve as internal caches
c. Architectural patterns & design principles:
– Separation of concerns: UI vs game logic vs AI engine
– Native‑managed boundary: C# ↔ C++ interop via DLL exports
– Algorithmic layering: core data structures at the bottom, search routines above, public API at top
d. Technologies/frameworks:
– .NET WPF (C#, XAML)
– Visual C++ (native DLL)
– P/Invoke for interop
– Bitboard representation, minimax variants, various search optimizations

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        AppX["App.xaml"]:::frontend
        AppC["App.xaml.cs"]:::frontend
        MainW["MainWindow.xaml"]:::frontend
        MainWC["MainWindow.xaml.cs"]:::frontend
        BoardX["ChessBoard.xaml"]:::frontend
        BoardC["ChessBoard.xaml.cs"]:::frontend
        UCX["UserControl1.xaml"]:::frontend
        UCC["UserControl1.xaml.cs"]:::frontend
    end

    subgraph "Game Logic (Managed)"
        Chess["Chess.cs"]:::logic
        Global["GlobalRule.cs"]:::logic
        Logic["LogicMap.cs"]:::logic
    end

    subgraph "Native AI Engine (DecisionTree DLL)"
        dllCPP["dllfunction.cpp"]:::engine
        dllH["dllfunction.h"]:::engine
        BBcpp["bitboard.cpp"]:::engine
        BBh["bitboard.h"]:::engine
        BTcpp["bittree.cpp"]:::engine
        BTh["bittree.h"]:::engine

        subgraph "Algorithms"
            Search["Search Tree Builder"]:::engine
            Minimax["Minimax/α‑β/NegaMax"]:::engine
            MoveOrder["Move‑ordering Heuristics"]:::engine
            HashMod["Zobrist Hashing & Transposition Table"]:::engine
        end

        Search <--> BBcpp
        Search <--> BTcpp
        Minimax --> MoveOrder
        Minimax --> HashMod
    end

    subgraph "Data Stores"
        History(("HistoryTable")):::datastore
        Zobolt(("ZobristHash")):::datastore
    end

    MainW -->|"UserEvent: ClickMove"| Chess
    Chess -->|"InvokeBestMove(state)"| dllCPP
    dllCPP -->|"PInvoke"| Search
    Search --> History
    Search --> Zobolt
    Minimax --> History
    Minimax --> Zobolt
    Search -->|"BestMove"| Chess
    Chess -->|"ApplyMove"| MainWC

    WPFsol["WpfApp.sln"]:::external
    README["README.md"]:::external
    Doc["Doc/"]:::external

    WPFsol --> AppX
    WPFsol --> dllCPP
    README --> Doc

    click AppX "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/App.xaml"
    click AppC "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/App.xaml.cs"
    click MainW "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/MainWindow.xaml"
    click MainWC "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/MainWindow.xaml.cs"
    click BoardX "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/ChessBoard.xaml"
    click BoardC "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/ChessBoard.xaml.cs"
    click UCX "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/UserControl1.xaml"
    click UCC "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/UserControl1.xaml.cs"
    click Chess "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/Chess.cs"
    click Global "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/GlobalRule.cs"
    click Logic "https://github.com/linxin8/chinese-chess/blob/master/WpfApp/LogicMap.cs"
    click dllCPP "https://github.com/linxin8/chinese-chess/blob/master/DecisionTree/dllfunction.cpp"
    click dllH "https://github.com/linxin8/chinese-chess/blob/master/DecisionTree/dllfunction.h"
    click BBcpp "https://github.com/linxin8/chinese-chess/blob/master/DecisionTree/bitboard.cpp"
    click BBh "https://github.com/linxin8/chinese-chess/blob/master/DecisionTree/bitboard.h"
    click BTcpp "https://github.com/linxin8/chinese-chess/blob/master/DecisionTree/bittree.cpp"
    click BTh "https://github.com/linxin8/chinese-chess/blob/master/DecisionTree/bittree.h"
    click WPFsol "https://github.com/linxin8/chinese-chess/blob/master/WpfApp.sln"
    click Doc "https://github.com/linxin8/chinese-chess/tree/master/Doc/"
    click README "https://github.com/linxin8/chinese-chess/blob/master/README.md"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef logic fill:#90EE90,stroke:#000,stroke-width:1px
    classDef engine fill:#FFA500,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFFF00,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
