# vytrg/quancapturegame architecture

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

- Interactive diagram: https://gitdiagram.com/vytrg/quancapturegame
- Repository: https://github.com/vytrg/quancapturegame

## Overview

##### Project Type and Purpose
- This is a monolithic, Python-based board game application (“Quan Capture Game”) that includes both the game engine and an AI opponent.
- The user interface is console/keyboard driven; core modules handle game rules, board representation, and AI move generation.

##### High-Level Components
a. Entry Point (UI Controller)
- app/main.py (and optionally root/main.py) – reads user input, renders the board, and invokes game logic.
b. Game Engine (Model + Controller)
- app/board.py & board.py – represents the game state, enforces rules, applies moves.
- square.py – cell/square abstraction on the board.
c. AI Engine
- minimax.py – search algorithm driver.
- heuristic.py – evaluation functions for board states.
- treenode.py – internal tree node structure for search.
d. Scoreboard Module
- app/scoreBoard.py – tracks, updates, and displays player scores.
e. Data & Assets
- data.py – configuration, constants (e.g., initial piece layout).
- image/ – any graphical assets (if used).
- requirements.txt – Python dependencies.

##### Relationships & Data Flow
- For human vs. AI modes, after a human move, UI Controller calls the AI Engine.
- AI Engine: minimax.py orchestrates search, uses treenode.py to construct the search tree and heuristic.py to evaluate leaves → returns best move.
- Game Engine updates its internal Board state → updates Scoreboard if captures occur.
- UI Controller re-renders the updated board and scores.

##### Architectural Patterns & Principles
- MVC-style separation:
- Model: Board, Square, Data
- View/Controller combined in app/main.py (input handling + rendering)
- Strategy pattern for AI: interchangeable heuristic functions plugged into the minimax driver.
- Single-process, synchronous flow (no microservices or external APIs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        UI1["app/main.py"]:::ui
        UI2["main.py"]:::ui
    end

    %% Game Engine Layer
    subgraph "Game Engine"
        BoardApp["app/board.py"]:::ge
        BoardCore["board.py"]:::ge
        Square["square.py"]:::ge
    end

    %% AI Engine Layer
    subgraph "AI Engine"
        Minimax["minimax.py: Search Controller"]:::ai
        Heuristic["heuristic.py: Evaluation Functions"]:::ai
        TreeNode["treenode.py: Search Tree Node"]:::ai
    end

    %% Scoreboard Module
    Scoreboard["app/scoreBoard.py"]:::score

    %% Data & Assets Layer
    subgraph "Data & Assets"
        Data["data.py: Config Constants"]:::data
        Assets["image/"]:::data
        Req["requirements.txt"]:::data
    end

    %% Connections
    UI1 -->|"apply_move()"| BoardApp
    UI2 -->|"apply_move()"| BoardApp
    UI1 -->|"get_best_move()"| Minimax
    UI2 -->|"get_best_move()"| Minimax
    Minimax -->|"uses heuristic"| Heuristic
    Minimax -->|"builds tree"| TreeNode
    Minimax -->|"best_move"| BoardApp
    BoardApp -->|"update_score()"| Scoreboard
    Scoreboard -->|"display()"| UI1
    Scoreboard -->|"display()"| UI2
    BoardApp -->|"render_state()"| UI1
    BoardApp -->|"render_state()"| UI2
    Data -->|"initial_config"| BoardApp
    Data -->|"initial_config"| BoardCore

    %% Click Events
    click UI1 "https://github.com/vytrg/quancapturegame/blob/main/app/main.py"
    click UI2 "https://github.com/vytrg/quancapturegame/blob/main/main.py"
    click BoardApp "https://github.com/vytrg/quancapturegame/blob/main/app/board.py"
    click BoardCore "https://github.com/vytrg/quancapturegame/blob/main/board.py"
    click Square "https://github.com/vytrg/quancapturegame/blob/main/square.py"
    click Minimax "https://github.com/vytrg/quancapturegame/blob/main/minimax.py"
    click Heuristic "https://github.com/vytrg/quancapturegame/blob/main/heuristic.py"
    click TreeNode "https://github.com/vytrg/quancapturegame/blob/main/treenode.py"
    click Scoreboard "https://github.com/vytrg/quancapturegame/blob/main/app/scoreBoard.py"
    click Data "https://github.com/vytrg/quancapturegame/blob/main/data.py"
    click Assets "https://github.com/vytrg/quancapturegame/tree/main/image/"
    click Req "https://github.com/vytrg/quancapturegame/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef ge fill:#E6FFE6,stroke:#00A000,color:#007700;
    classDef ai fill:#FFE6CC,stroke:#FF8C00,color:#CC6600;
    classDef data fill:#FFF5CC,stroke:#CCCC00,color:#999900;
    classDef score fill:#E6FFE6,stroke:#00A000,color:#007700;
```
