# guilhermekotchergenko/connect-4-ai architecture

> Architecture diagram of the GitHub repository guilhermekotchergenko/connect-4-ai, 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/guilhermekotchergenko/connect-4-ai
- Repository: https://github.com/guilhermekotchergenko/connect-4-ai

## Overview

##### Project Type and Purpose
- This is a standalone Python application plus a companion Jupyter notebook for running experiments.
- It implements a Connect Four game engine, multiple AI agents (ID3, ensemble bagging, MCTS, parallel MCTS), a terminal‐based UI, data logging, model training, and visualization (Graphviz + matplotlib).

##### High-Level Components
a. User Interfaces
- Terminal CLI (main.py in “Nanahira Connect 4!”)
- Jupyter Notebook (connect_four.ipynb)
b. Core Game Engine
- State representation (board.py, constants.py)
- Rule enforcement & win detection
c. AI Agents
- Random baseline
- ID3 Decision Tree (ai_id3.py + train logic)
- Bagging Ensemble (ensemble builder, majority vote)
- Monte-Carlo Tree Search (ai_mcts.py, parallel via multiprocessing)
d. Orchestration & Menus
- Menu modules (menu.py, MenuAISelection.py, *ConfigMenu.py) for steering game mode and AI selection
e. Persistence & Data
- CSV logs: datasets/match_log.csv & Nanahira/match_log.csv
- Model snapshots: *.pkl + *.hash under Nanahira
f. Visualization & Reporting
- Graphviz exports (images/*.dot → .png via external graphviz)
- Matplotlib plots (images/)
g. External Dependencies
- Graphviz system install
- Python libraries (listed in requirements.txt)
- Multiprocessing for parallel MCTS

##### Relationships and Data Flows
- User (CLI or Notebook) → invokes Orchestration layer → Game Engine.
- Game Engine → calls selected AI Agent to compute next move.
- After each game: Orchestration → appends flattened game history to datasets/<match_log>.
- Triggering a tree‐based AI → reads full CSV log → retrains model → writes *.pkl + *.hash.
- Optional: Notebook → batch runs multiple match-ups → writes performance logs → generates plots.
- Visualization modules invoke Graphviz CLI to render .dot files into .png.

##### Architectural Patterns & Design Principles
- Modular separation: UI (menus) vs. core engine vs. AI plugins vs. persistence vs. visualization.
- Pluggable AI components behind a common “Agent” interface in HandleAivsAI.py / HandlePvaiId3.py.
- Self-play training loop: closed‐loop feedback for model re‐training.
- Concurrency: MCTS parallel rollouts via Python’s multiprocessing module.

##### Essential Elements Checklist
[ ] Call out external Graphviz and multiprocessing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "User Interfaces"
        CLI["Terminal CLI: main.py"]:::ui
        Notebook["Jupyter Notebook: connect_four.ipynb"]:::ui
    end

    %% Backend Layer
    subgraph "Orchestration & Menus"
        Orchestrator["Orchestrator: menu.py, MenuAISelection.py"]:::backend
    end

    subgraph "Core Game Engine"
        Board["State Representation: board.py"]:::backend
        Constants["Constants: constants.py"]:::backend
        Rule["Rule Enforcement & Win Detection"]:::backend
        LoggerMod["Match Logging: match_logger.py"]:::backend
    end

    subgraph "AI Agents"
        Random["Random Baseline"]:::ai
        ID3["ID3 Agent: ai_id3.py, HandlePvaiId3.py"]:::ai
        Bagging["Bagging Ensemble: HandleAivsAI.py"]:::ai
        MCTS["MCTS Agent: ai_mcts.py"]:::ai
    end

    subgraph "Configuration Menus"
        Id3Menu["ID3 Config Menu: Id3ConfigMenu.py"]:::backend
        AivsMenu["Bagging Config Menu: AivsAIConfigMenu.py"]:::backend
        MCTSMenu["MCTS Config Menu: MCTSConfigMenu.py"]:::backend
    end

    %% Data Layer
    subgraph "Datasets & Models"
        LogsCSV["Match Logs CSV"]:::data
        OtherCSVs["Other CSVs"]:::data
        PerfLog["Performance Log CSV"]:::data
        ModelStore["Model Snapshots (.pkl/.hash)"]:::data
    end

    %% Visualization Layer
    subgraph "Visualization & Reporting"
        Graphviz["Graphviz Exports (.dot→.png)"]:::viz
        Matplotlib["Matplotlib Plots"]:::viz
    end

    %% External Dependencies
    subgraph "External"
        GraphvizExt["Graphviz CLI"]:::external
        Multiproc["Multiprocessing"]:::external
        Requirements["requirements.txt"]:::external
    end

    %% Flows
    CLI -->|invokes| Orchestrator
    Notebook -->|invokes| Orchestrator
    Orchestrator -->|starts game| Board
    Orchestrator -->|starts game| Constants
    Board -->|enforces rules| Rule
    Rule -->|logs move| LoggerMod
    Orchestrator -->|selects agent| Random
    Orchestrator -->|selects agent| ID3
    Orchestrator -->|selects agent| Bagging
    Orchestrator -->|selects agent| MCTS
    ID3 -->|uses config| Id3Menu
    Bagging -->|uses config| AivsMenu
    MCTS -->|uses config| MCTSMenu
    LoggerMod -->|writes| LogsCSV
    LoggerMod -->|writes| OtherCSVs
    LogsCSV -->|trains| ID3
    LogsCSV -->|trains| Bagging
    LogsCSV -->|trains| MCTS
    ID3 -->|saves model| ModelStore
    Bagging -->|saves model| ModelStore
    MCTS -->|saves model| ModelStore
    Notebook -->|batch runs| PerfLog
    PerfLog -->|plots| Matplotlib
    Graphviz -->|renders| GraphvizExt
    Matplotlib -->|requires| Requirements
    MCTS -->|parallel rollouts| Multiproc

    %% Click Events
    click CLI "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/main.py"
    click Notebook "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/connect_four.ipynb"
    click Board "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/board.py"
    click Constants "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/constants.py"
    click LoggerMod "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/match_logger.py"
    click ID3 "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/ai_id3.py"
    click Bagging "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/HandleAivsAI.py"
    click MCTS "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/ai_mcts.py"
    click Orchestrator "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/menu.py"
    click Id3Menu "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/Id3ConfigMenu.py"
    click AivsMenu "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/AivsAIConfigMenu.py"
    click MCTSMenu "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/Nanahira/MCTSConfigMenu.py"
    click LogsCSV "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/datasets/match_log.csv"
    click PerfLog "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/datasets/performance_log.csv"
    click Graphviz "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/images/minha_arvore.dot"
    click Requirements "https://github.com/guilhermekotchergenko/connect-4-ai/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef ai fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef viz fill:#e2d5ff,stroke:#4b0082,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#666,stroke-width:1px
```
