# soniquentin/abalone_ai_minimax architecture

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

- Interactive diagram: https://gitdiagram.com/soniquentin/abalone_ai_minimax
- Repository: https://github.com/soniquentin/abalone_ai_minimax

## Overview

##### Project type and purpose
- This is an AI project for the board game Abalone. It’s neither a web service nor a distributed system but a standalone Python application with:
- A simple GUI (HTML/CSS/JS)
- A game engine (board, game state, match manager)
- An AI agent implementing Minimax with a transposition table and heuristic functions
- Test scripts to tune and benchmark the agent

##### File structure
- src/GUI: static UI files (index.html, main.css, main.js)
- src/main_abalone.py: entry point that bootstraps the GUI + game engine
- src/master_abalone.py: orchestrates the match loop (Controller)
- src/game_state_abalone.py, src/board_abalone.py, src/player_abalone.py: core model classes provided by the course
- src/my_player.py: your AI agent implementing Minimax + optimizations
- src/TranspositionTable.py: caching layer to avoid re-evaluating states
- src/coords.py: coordinate-conversion utilities used by both UI (to render stones) and the agent
- tests/: scripts and data for heuristic tuning and tournament benchmarking

##### README for architecture cues
- The system is structured roughly as MVC:
– View: GUI (served locally)
– Controller: main_abalone.py + master_abalone.py
– Model: board_abalone.py, game_state_abalone.py
- The AI agent (“my_player.py”) plugs into the Controller as a Player subclass
- A Transposition Table caches Minimax evaluations

##### Essential elements to capture
- Data flow: user inputs, method calls, cache hits/misses
- Design patterns (e.g., “Minimax search loop”, “Strategy: Player subclass”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User (Human)"]:::external

    %% UI Layer
    subgraph "UI Layer"
        direction TB
        idxHtml["index.html"]:::ui
        mainCss["main.css"]:::ui
        mainJs["main.js"]:::ui
    end

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        entry["main_abalone.py"]:::controller
        orchestrator["master_abalone.py"]:::controller
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        board["board_abalone.py"]:::model
        gamestate["game_state_abalone.py"]:::model
        playerIface["player_abalone.py"]:::model
    end

    %% AI & Cache Layer
    subgraph "AI/Cache Layer"
        direction TB
        aiAgent["my_player.py\n(Minimax Agent)"]:::ai
        tpTable["TranspositionTable.py\n(Cache)"]:::ai
        coords["coords.py\n(Coordinate Converter)"]:::ai
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        rndSearch["random_search.py"]:::test
        tuneSearch["tuning_local_search.py"]:::test
        tournament["tournament.py"]:::test
        resultNotebook["look_result_tournament.ipynb"]:::test
    end

    %% Connections
    User --> idxHtml
    idxHtml --> mainJs
    mainJs --> entry
    entry --> orchestrator
    orchestrator --> board
    orchestrator --> gamestate
    orchestrator --> playerIface
    playerIface --> aiAgent
    aiAgent --> tpTable
    aiAgent --> coords
    aiAgent --> board
    aiAgent --> gamestate
    rndSearch --> aiAgent
    tuneSearch --> aiAgent
    tournament --> aiAgent
    rndSearch --> tpTable
    tuneSearch --> tpTable
    tournament --> tpTable

    %% Click Events
    click idxHtml "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/GUI/index.html"
    click mainCss "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/GUI/main.css"
    click mainJs "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/GUI/main.js"
    click entry "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/main_abalone.py"
    click orchestrator "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/master_abalone.py"
    click board "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/board_abalone.py"
    click gamestate "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/game_state_abalone.py"
    click playerIface "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/player_abalone.py"
    click aiAgent "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/my_player.py"
    click tpTable "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/TranspositionTable.py"
    click coords "https://github.com/soniquentin/abalone_ai_minimax/blob/master/src/coords.py"
    click rndSearch "https://github.com/soniquentin/abalone_ai_minimax/blob/master/tests/random_search.py"
    click tuneSearch "https://github.com/soniquentin/abalone_ai_minimax/blob/master/tests/tuning_local_search.py"
    click tournament "https://github.com/soniquentin/abalone_ai_minimax/blob/master/tests/tournament.py"
    click resultNotebook "https://github.com/soniquentin/abalone_ai_minimax/blob/master/tests/look_result_tournament.ipynb"

    %% Styles
    classDef ui fill:#E0F7FA,stroke:#000,stroke-width:1px
    classDef controller fill:#FFF9C4,stroke:#000,stroke-width:1px
    classDef model fill:#C8E6C9,stroke:#000,stroke-width:1px
    classDef ai fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef test fill:#ECEFF1,stroke:#000,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
