# gruhit13/connect4-alphazero architecture

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

- Interactive diagram: https://gitdiagram.com/gruhit13/connect4-alphazero
- Repository: https://github.com/gruhit13/connect4-alphazero

## Overview

##### Key project components
- Frontend (React UI):
– Located in the “frontend” folder.
– Contains a standard React setup with components, styling, and build configuration.
– Likely responsible for visualizing the game board, user interactions, and possibly rendering the video demonstration.

- Backend Game Engine (Python):
– Found in the “src” directory.
– Contains core modules for game simulation and AlphaZero logic:
⮞ agent.py: Likely the game-playing agent integrating MCTS and NN evaluations.
⮞ mcts.py: Implements Monte Carlo Tree Search for exploring moves.
⮞ arena.py and game.py: Manage game environments and simulations (self-play, game rule enforcement).
⮞ trainer.py: Handles iterative self-play and training of the neural network.
⮞ model.py: Defines or interfaces with the neural network used to evaluate positions, with “Models/azv3.pt” holding the trained parameters.
⮞ view_board.py: Possibly responsible for rendering the game board state for debugging or CLI purposes.
⮞ config.py and buffer.py: Likely responsible for configuration settings (e.g., hyperparameters) and managing experience replay or temporary game data.

- Data / Model Storage:
– “Models” folder storing the neural network file (azv3.pt) that is utilized during inference and training.

##### Relationships and interactions
- The Frontend and Backend:
– Even though there is no explicit API server (e.g., Flask or FastAPI) visible in the file tree, it is useful to assume that the frontend is intended for user interaction (displaying the board, game state) and could be communicating with the Python backend through an API layer or via local process execution.

- Within the Backend:
– The “agent.py” module likely ties together the MCTS (“mcts.py”), game simulation (from “game.py” and “arena.py”), and neural network evaluation (via “model.py” using the “Models/azv3.pt” file).
– The “trainer.py” module uses self-play (running simulations in “arena.py”/“game.py”) to generate training data that refines the neural network.
– “buffer.py” might store game states or experience data exchanged between self-play and trainer modules.

##### Architectural patterns and important design principles
- Separation of concerns is clearly evident:
– The Frontend (UI rendering, user interaction) is cleanly separated from the Game Engine (simulation, decision-making, training).
– The backend further subdivides concerns into game simulation, search algorithm (MCTS), and training/learning (AlphaZero components: policy and value network roles).
- Modularity and extensibility:
– Each module (agent, MCTS, trainer, etc.) performs a specific role, enabling easier debugging and future upgrades.
- Integration of Neural Networks:
– The project uses neural networks (as indicated by the .pt file and model.py) for both evaluating game states (value network) and suggesting move probabilities (policy network). This ensures that the system combines search (MCTS) with predictive capabilities (deep evaluation).

##### Detail
- That every module or key file from the “src” directory is represented with its functional relationship (e.g., agent uses mcts; trainer updates model with data from arena).
- Even if some parts are not fully connected by an explicit API, it is beneficial to illustrate how the game state and decision chain flow from user interaction to backend AI decision-making and back to visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    FE["Frontend (React UI)"]:::frontend

    %% Backend Subsystem
    subgraph "Backend: Game Engine & AI"
        BS["Game Simulation (game.py, arena.py)"]:::simulation
        BV["Board Visualization (view_board.py)"]:::simulation
        AG["Game Playing Agent (agent.py)"]:::decision
        MC["MCTS (mcts.py)"]:::decision
        NN["Model & Evaluation (model.py, azv3.pt)"]:::model
        TR["Training Module (trainer.py)"]:::training
        BU["Data Buffer (buffer.py)"]:::training
        CF["Configuration (config.py)"]:::training
    end

    %% Data Flow
    FE -->|"triggerGameSim"| BS
    BS -->|"updateBoardState"| BV
    BS -->|"sendGameState"| AG
    AG -->|"invokeMCTS"| MC
    MC -->|"evaluateState"| NN
    NN -->|"returnEvaluation"| AG
    BS -->|"simulateOutcome"| BU
    BU -->|"provideTrainingData"| TR
    CF -->|"supplyHyperparams"| TR
    TR -->|"updateNeuralModel"| NN
    BV -->|"displayBoard"| FE

    %% Click Events
    click FE "https://github.com/gruhit13/connect4-alphazero/tree/main/frontend/"
    click AG "https://github.com/gruhit13/connect4-alphazero/blob/main/src/agent.py"
    click MC "https://github.com/gruhit13/connect4-alphazero/blob/main/src/mcts.py"
    click BS "https://github.com/gruhit13/connect4-alphazero/blob/main/src/game.py"
    click BS "https://github.com/gruhit13/connect4-alphazero/blob/main/src/arena.py"
    click TR "https://github.com/gruhit13/connect4-alphazero/blob/main/src/trainer.py"
    click NN "https://github.com/gruhit13/connect4-alphazero/blob/main/src/model.py"
    click NN "https://github.com/gruhit13/connect4-alphazero/blob/main/Models/azv3.pt"
    click BU "https://github.com/gruhit13/connect4-alphazero/blob/main/src/buffer.py"
    click BV "https://github.com/gruhit13/connect4-alphazero/blob/main/src/view_board.py"
    click CF "https://github.com/gruhit13/connect4-alphazero/blob/main/src/config.py"

    %% Styles
    classDef frontend fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef simulation fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef decision fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef model fill:#d5f5e3,stroke:#229954,stroke-width:2px;
    classDef training fill:#f5cba7,stroke:#d35400,stroke-width:2px;
```
