# ahmadrazakhawaja/chess-game-ai-project architecture

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

- Interactive diagram: https://gitdiagram.com/ahmadrazakhawaja/chess-game-ai-project
- Repository: https://github.com/ahmadrazakhawaja/chess-game-ai-project

## Overview

##### Project Type and Purpose
- This is a full-stack, standalone chess game built in Python using the pygame module for the GUI.
- It supports two playing modes: human vs. human and human vs. AI. The AI is implemented via a recursive Minimax algorithm with alpha-beta pruning.
- The project uses a data structure (an 8×8 2D array) to model the chessboard where each cell (tile) holds the current chess piece, and the chess rules (legal moves, special moves like castling, en passant, etc.) are implemented in several modules.

##### Analysis of the File Structure
- Top-Level Files and Directories:
- README.md – Provides project description, features, and usage instructions.
- playchess.py – The main entry point integrating all functionalities, handling game loops and pygame GUI interactions.
- requirements.txt – Lists necessary Python modules including pygame.
- Directories:
- board – Contains files (chessboard, move, tile) that define the overall board layout, initialization, and movement logic.
- pieces – Contains individual files for each type of chess piece (bishop, king, knight, etc.). Each piece defines its attributes and legal move logic.
- player – Contains AI.py which implements the AI's logic using the Minimax algorithm with alpha-beta pruning.
- chessart – Stores chess piece images used by the GUI.
- project_images – Contains images used for various game screens.
- Notable Architectural Patterns:
- Separation of concerns: The board mechanics, piece behavior, AI logic, and GUI elements are separated into different modules/directories.
- Object-Oriented Programming (OOP): Classes are used to encapsulate properties and behaviors (e.g., each chess piece, board, and tile).
- Modularity: Each component (board, pieces, player) is self-contained and can be updated independently.

##### Key Components and Their Interactions
a. Main Components:
- Game Entry Point (playchess.py): Initializes the game, loads configurations, and starts the pygame GUI event loop.
- Board Component (board directory):
- Chessboard Initialization (chessboard.py): Sets up the 8×8 board using Tile objects.
- Move Logic (move.py): Handles game rules like castling, en passant, and verifying valid moves.
- Tile Management (tile.py): Represents individual board cells holding a number and a chess piece.
- Pieces Component (pieces directory): Defines all chess pieces with attributes (alliance, position) and methods to determine legal moves.
- AI Component (player directory):
- AI Logic (AI.py): Implements the Minimax algorithm with alpha-beta pruning to compute the best move.
- GUI Component:
- Pygame Module: Used in playchess.py for rendering the game screen, handling player input, and displaying images from chessart and project_images directories.

b. Relationships and Interactions:
- The Game Entry Point (playchess.py) serves as the orchestration layer:
- It instantiates the chessboard and tile objects from the board module, populating it with chess pieces.
- It processes user interactions (moves), updates the board state, and redraws the GUI via pygame.
- When playing against the AI, it calls the AI logic (in player/AI.py) to determine the computer’s move.
- Board interacts with Pieces:
- The chessboard maintains pointers to chess pieces (defined in the pieces directory) within its tile cells.
- Movement functions in move.py use piece-specific legal move calculations.
- The GUI fetches images from the chessart and project_images folders to visually represent different pieces and game-state indicators.

c. Architectural Patterns and Design Principles:
- A modular, layered approach where the UI layer (playchess.py and pygame) is separate from the game logic (board, pieces) and AI.
- Clear separation of responsibilities ensures that changes in one area (such as the AI strategy or move rules) have minimal impact on the GUI or board layout.
- Use of OOP encapsulates state and behaviors, making the system extendable (e.g., for additional features or improved AI).

d. Relevant Technologies, Frameworks, or Libraries:
- Python and its core libraries.
- Pygame for game graphics and event handling.
- Custom algorithms for the AI (Minimax with alpha-beta pruning).

##### Elements
- Clear labels for each major component: Game Entry Point, Board, Pieces, AI, and GUI.
- From playchess.py to board initialization.
- From board to pieces (association within tiles).
- From playchess.py to AI (when in AI mode).
- From playchess.py to pygame for rendering.
- Logic components (board, move logic, piece classes).
- GUI components (display layer using pygame and image assets).
- Algorithmic components (AI logic).
- Optionally, include notes on external assets (chessart images) as part of the GUI module.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Game Core"
        A["Game Entry Point (playchess.py)"]:::entry
        subgraph "Board Component"
            B["Chessboard Initialization (chessboard.py)"]:::logic
            C["Move Logic (move.py)"]:::logic
            D["Tile Management (tile.py)"]:::logic
        end
        E["Pieces Definitions (pieces/)"]:::logic
        F["AI Logic (Minimax Algorithm) (player/AI.py)"]:::ai
    end
    subgraph "GUI Layer"
        G["Pygame GUI"]:::gui
        subgraph "GUI Assets"
            H["Chess Piece Images (chessart/)"]:::asset
            I["Other Game Images (project_images/)"]:::asset
        end
    end

    A -->|"initializes"| B
    A -->|"processes_moves"| C
    A -->|"creates_tiles"| D
    B -->|"populates"| E
    D -->|"associates_with"| E
    A -->|"triggers_AI_move"| F
    F -->|"computes_move"| B
    A -->|"renders_GUI"| G
    B -->|"updates_display"| G
    G -->|"loads_asset"| H
    G -->|"loads_asset"| I

    click A "https://github.com/ahmadrazakhawaja/chess-game-ai-project/blob/master/playchess.py"
    click B "https://github.com/ahmadrazakhawaja/chess-game-ai-project/blob/master/board/chessboard.py"
    click C "https://github.com/ahmadrazakhawaja/chess-game-ai-project/blob/master/board/move.py"
    click D "https://github.com/ahmadrazakhawaja/chess-game-ai-project/blob/master/board/tile.py"
    click E "https://github.com/ahmadrazakhawaja/chess-game-ai-project/tree/master/pieces/"
    click F "https://github.com/ahmadrazakhawaja/chess-game-ai-project/blob/master/player/AI.py"
    click H "https://github.com/ahmadrazakhawaja/chess-game-ai-project/tree/master/chessart/"
    click I "https://github.com/ahmadrazakhawaja/chess-game-ai-project/tree/master/project_images/"

    classDef entry fill:#E8F8F5,stroke:#1abc9c,stroke-width:2px;
    classDef logic fill:#FDFEFE,stroke:#3498db,stroke-width:2px;
    classDef ai fill:#FCF3CF,stroke:#f1c40f,stroke-width:2px;
    classDef gui fill:#EBF5FB,stroke:#2ecc71,stroke-width:2px;
    classDef asset fill:#FDEDEC,stroke:#e74c3c,stroke-width:2px;
```
