# shirne/chinese_chess architecture

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

- Interactive diagram: https://gitdiagram.com/shirne/chinese_chess
- Repository: https://github.com/shirne/chinese_chess

## Overview

##### Project type and purpose
- This is a cross-platform Flutter application (mobile, web, desktop) implementing a Chinese Chess client with a built-in rule engine and optional external engines via plugins.
- It’s not a server-backed system; it’s a standalone client with pluggable “engine” modules for move generation.

##### File structure
Top-level directories:
- android / ios / macos / linux / windows / web – platform-specific embedding code
- lib – core Dart code, subdivided into:
– components (UI widgets for board, dialogs, controls)
– widgets (reusable UI elements)
– models (game state, settings, events)
– driver (player/robot/online drivers)
– html (web/Win32 FFI abstractions)
– foundation (app-wide notifiers, globals)
– l10n (localization)
– utils (helper functions)
– main.dart (app entry)
- assets – images, skins, sounds
- plugins – engine_interface and per-platform engine implementations (elephanteye, pikafish, etc.)
- test – unit and widget tests

##### Review README insights
- Implements full chess rules, FEN/PGN import-export, multiple game modes (player vs player, player vs bot, web bot).
- Windows build integrates the Elephanteye engine; other platforms fall back to the bundled XQLite engine.
- Multi-language support, sound effects (except Linux), platform adaptation via Flutter.

##### Main components and interactions
a. UI Layer (Flutter widgets & components)
- lib/components & lib/widgets – board rendering, dialogs, input controls
- lib/theme, lib/setting – theming and user preferences
b. Application Logic (Dart)
- lib/models/game_manager – central state machine for game rules (move validation, win detection)
- lib/driver – abstracts move sourcing:
– driver_user (touch/click input)
– driver_robot (built-in XQLite or external engine via engine_interface)
– driver_online (future online play)
- lib/foundation/customer_notifier – state notification to UI
c. Engine Interface Layer
- plugins/engine_interface – defines UCCI protocol, move-request API, logging, abstract model objects
- lib/html/ffi & platform plugin code – FFI wrappers for Windows, web, Linux, macOS to load native engine binaries
d. External Engine Plugins
- plugins/engine_* (engine_darwin, engine_windows, engine_linux, engine_android, engine_web) – platform assets (elephanteye, pikafish) and Dart wrappers
e. Platform Embedding
- android/, ios/, macos/, linux/, windows/, web/ – native scaffolds generated by Flutter, plus any platform overrides (CMakeLists, Podfiles, etc.)
f. Assets & Localization
- assets/skins, assets/sounds – game visuals and audio
- lib/l10n – .arb files and generated Dart localization

##### Architectural patterns and principles
- Layered architecture: UI → Application Logic → Engine Interface → Native Engine
- Separation of concerns: rendering vs. state vs. engine communication
- Flutter’s reactive pattern: ChangeNotifier & Provider (or similar) to push state to UI
- Plugin-based extensibility: engine_interface defines a contract, platform packages implement it

##### Final checklist
- Clear labels for every component (include directory/name)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        main["App Entry Point\nlib/main.dart"]:::ui
        components["Components\nlib/components"]:::ui
        widgets["Widgets\nlib/widgets"]:::ui
        theme["Theme & Settings\nlib/theme.dart, lib/setting.dart"]:::ui
    end

    subgraph "Application Logic"
        game_manager["Game Manager\nlib/models/game_manager.dart"]:::core
        models["Models\nlib/models"]:::core
        driver_user["User Driver\nlib/driver/driver_user.dart"]:::core
        driver_robot["Robot Driver\nlib/driver/driver_robot.dart"]:::core
        driver_online["Online Driver\nlib/driver/driver_online.dart"]:::core
        player_driver["Player Driver\nlib/driver/player_driver.dart"]:::core
        notifier["Notifier\nlib/foundation/customer_notifier.dart"]:::core
    end

    subgraph "Engine Interface Layer"
        ucci_api["UCCI Protocol API\nplugins/engine_interface/lib/src/engine_interface.dart"]:::plugin
        model_iface["Model Objects\nplugins/engine_interface/lib/src/model.dart"]:::plugin
        logger["Logger\nplugins/engine_interface/lib/src/logger.dart"]:::plugin
        dart_iface["Dart Interface\nplugins/engine_interface/lib/engine_interface.dart"]:::plugin
    end

    subgraph "FFI Wrappers"
        html_ffi["HTML FFI\nlib/html/ffi.dart"]:::plugin
        win32_ffi["Win32 FFI\nlib/html/win32.dart"]:::plugin
    end

    subgraph "Native Engine Plugins"
        eng_android["Android Engine\nplugins/engine_android/lib/engine_android.dart"]:::native
        eng_darwin["Darwin Engine\nplugins/engine_darwin/lib/engine_darwin.dart"]:::native
        eng_darwin_assets["Darwin Assets\nplugins/engine_darwin/assets/engines"]:::native
        eng_linux["Linux Engine\nplugins/engine_linux/lib/engine_linux.dart"]:::native
        eng_linux_assets["Linux Assets\nplugins/engine_linux/assets/engines"]:::native
        eng_windows["Windows Engine\nplugins/engine_windows/lib/engine_windows.dart"]:::native
        eng_windows_assets["Windows Assets\nplugins/engine_windows/assets/engines"]:::native
        eng_web["Web Engine\nplugins/engine_web/lib/engine_web.dart"]:::native
    end

    subgraph "Platform Host"
        android["Android Host\nandroid/"]:::host
        ios["iOS Host\nios/"]:::host
        macos["macOS Host\nmacos/"]:::host
        linux["Linux Host\nlinux/"]:::host
        windows["Windows Host\nwindows/"]:::host
        web_host["Web Host\nweb/"]:::host
    end

    subgraph "Assets & Localization"
        skins["Skins\nassets/skins"]:::assets
        sounds["Sounds\nassets/sounds"]:::assets
        loc_en["app_en.arb\nlib/l10n/app_en.arb"]:::assets
        loc_zh["app_zh.arb\nlib/l10n/app_zh.arb"]:::assets
        loc_gen["Generated Loc\nlib/l10n/generated/app_localizations.dart"]:::assets
    end

    %% Connections
    main --> components
    main --> widgets
    main --> theme

    components -->|user actions| game_manager
    widgets -->|render updates| game_manager
    theme -->|preferences| components
    theme -->|preferences| widgets

    game_manager -->|state events| notifier
    notifier --> components

    game_manager -->|uses models| models

    game_manager -->|move request| driver_user
    game_manager -->|move request| player_driver
    game_manager -->|move request| driver_robot
    game_manager -->|move request| driver_online

    driver_user -->|Dart objects| dart_iface
    player_driver -->|Dart objects| dart_iface
    driver_robot -->|UCCI request| dart_iface
    driver_online -->|stub API| dart_iface

    dart_iface -->|protocol calls| ucci_api
    ucci_api -->|defines data| model_iface
    ucci_api -->|logs| logger

    dart_iface -->|load engine| html_ffi
    dart_iface -->|load engine| win32_ffi

    html_ffi -->|loads| eng_web
    win32_ffi -->|loads| eng_windows
    win32_ffi -->|loads| eng_darwin
    win32_ffi -->|loads| eng_linux
    win32_ffi -->|loads| eng_android

    eng_android -->|move response| dart_iface
    eng_darwin -->|move response| dart_iface
    eng_linux -->|move response| dart_iface
    eng_windows -->|move response| dart_iface
    eng_web -->|move response| dart_iface

    dart_iface -->|move update| driver_robot
    dart_iface -->|move update| driver_user
    dart_iface -->|move update| player_driver
    dart_iface -->|move update| driver_online

    driver_user -->|update| game_manager
    player_driver -->|update| game_manager
    driver_robot -->|update| game_manager
    driver_online -->|update| game_manager

    game_manager -->|UI update| components

    skins --> components
    sounds --> components
    loc_en --> components
    loc_zh --> components
    loc_gen --> components

    android --> html_ffi
    ios --> html_ffi
    macos --> win32_ffi
    linux --> win32_ffi
    windows --> win32_ffi
    web_host --> html_ffi

    %% Click Events
    click components "https://github.com/shirne/chinese_chess/tree/master/lib/components"
    click widgets "https://github.com/shirne/chinese_chess/tree/master/lib/widgets"
    click theme "https://github.com/shirne/chinese_chess/blob/master/lib/theme.dart"
    click theme "https://github.com/shirne/chinese_chess/blob/master/lib/setting.dart"
    click game_manager "https://github.com/shirne/chinese_chess/blob/master/lib/models/game_manager.dart"
    click models "https://github.com/shirne/chinese_chess/tree/master/lib/models"
    click driver_user "https://github.com/shirne/chinese_chess/blob/master/lib/driver/driver_user.dart"
    click driver_robot "https://github.com/shirne/chinese_chess/blob/master/lib/driver/driver_robot.dart"
    click driver_online "https://github.com/shirne/chinese_chess/blob/master/lib/driver/driver_online.dart"
    click player_driver "https://github.com/shirne/chinese_chess/blob/master/lib/driver/player_driver.dart"
    click notifier "https://github.com/shirne/chinese_chess/blob/master/lib/foundation/customer_notifier.dart"
    click ucci_api "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_interface/lib/src/engine_interface.dart"
    click model_iface "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_interface/lib/src/model.dart"
    click logger "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_interface/lib/src/logger.dart"
    click dart_iface "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_interface/lib/engine_interface.dart"
    click html_ffi "https://github.com/shirne/chinese_chess/blob/master/lib/html/ffi.dart"
    click win32_ffi "https://github.com/shirne/chinese_chess/blob/master/lib/html/win32.dart"
    click eng_android "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_android/lib/engine_android.dart"
    click eng_darwin "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_darwin/lib/engine_darwin.dart"
    click eng_darwin_assets "https://github.com/shirne/chinese_chess/tree/master/plugins/engine_darwin/assets/engines"
    click eng_linux "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_linux/lib/engine_linux.dart"
    click eng_linux_assets "https://github.com/shirne/chinese_chess/tree/master/plugins/engine_linux/assets/engines"
    click eng_windows "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_windows/lib/engine_windows.dart"
    click eng_windows_assets "https://github.com/shirne/chinese_chess/tree/master/plugins/engine_windows/assets/engines"
    click eng_web "https://github.com/shirne/chinese_chess/blob/master/plugins/engine_web/lib/engine_web.dart"
    click android "https://github.com/shirne/chinese_chess/tree/master/android/"
    click ios "https://github.com/shirne/chinese_chess/tree/master/ios/"
    click macos "https://github.com/shirne/chinese_chess/tree/master/macos/"
    click linux "https://github.com/shirne/chinese_chess/tree/master/linux/"
    click windows "https://github.com/shirne/chinese_chess/tree/master/windows/"
    click web_host "https://github.com/shirne/chinese_chess/tree/master/web/"
    click skins "https://github.com/shirne/chinese_chess/tree/master/assets/skins"
    click sounds "https://github.com/shirne/chinese_chess/tree/master/assets/sounds"
    click loc_en "https://github.com/shirne/chinese_chess/blob/master/lib/l10n/app_en.arb"
    click loc_zh "https://github.com/shirne/chinese_chess/blob/master/lib/l10n/app_zh.arb"
    click loc_gen "https://github.com/shirne/chinese_chess/blob/master/lib/l10n/generated/app_localizations.dart"
    click main "https://github.com/shirne/chinese_chess/blob/master/lib/main.dart"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#037FFF,color:#000
    classDef core fill:#DFF7D8,stroke:#2E8B57,color:#000
    classDef plugin fill:#FFE5B4,stroke:#FF8C00,color:#000
    classDef native fill:#FFD6D6,stroke:#FF0000,color:#000
    classDef host fill:#E0E0E0,stroke:#808080,color:#000
    classDef assets fill:#FFF5BA,stroke:#FFD700,color:#000
```
