# dhakalnirajan/baghchal-rl architecture

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

- Interactive diagram: https://gitdiagram.com/dhakalnirajan/baghchal-rl
- Repository: https://github.com/dhakalnirajan/baghchal-rl

## Overview

##### Project Type and Main Purpose
- This is a board game implementation of Baagh Chaal, with a twist: the tiger player is powered by a neural network – accelerated with CUDA – and, in one variant (AlphaBaghChal), enhanced with Monte Carlo Tree Search (MCTS) for decision making.
- The project exists in two flavors: a CPU-based version (baaghchaal.cpp and main.c with cuda_kernels.cu) and an enhanced version with MCTS (alphabaghchal.c, alphabaghchal_cuda.cu, alphabaghchal_mcts.c).

##### File Structure to Identify Logical Components
- Top-Level Files (outside the AlphaBaghChal folder):
- main.c: Hosts game logic, initialization, user interaction, and integrates with the CUDA kernels.
- baaghchaal.cpp: CPU-only implementation with similar game logic but without CUDA.
- cuda_kernels.cu: Contains CUDA kernel functions for neural network computations.
- README.md and LICENSE.md: Provides overall project documentation.
- Inside the AlphaBaghChal Directory:
- alphabaghchal.c / alphabaghchal.h: Contains game logic and integration with MCTS.
- alphabaghchal_cuda.cu: CUDA kernels for neural network computations (mirroring cuda_kernels.cu).
- alphabaghchal_mcts.c / alphabaghchal_mcts.h: Implements the Monte Carlo Tree Search algorithm for improved AI moves.
- A README.md providing detailed explanations specific to the MCTS enhanced version.

##### Main Components
a. Game Engine & User Interface:
– Modules: main.c or alphabaghchal.c (depending on the variant) and baaghchaal.cpp.
– Responsibilities: Display board state, process user input, manage game state (placement and movement phases), and check game over conditions.
b. Neural Network Engine:
– Modules: Neural network data structures (NN definition in main.c/alphabaghchal.c) and training functions.
– Key Points: One hidden layer network, forward pass (with ReLU activation), softmax for probability distribution, and backpropagation routine.
– Note that both versions initialize and train a neural network (one with CUDA and one on CPU).
c. CUDA Acceleration:
– Modules: cuda_kernels.cu and alphabaghchal_cuda.cu.
– Responsibilities: Provide GPU-accelerated neural network computations, including the forward pass and backpropagation kernels.
– Include details such as: the use of CUDA kernels, shared memory, and external C wrappers for integration.
d. Monte Carlo Tree Search (MCTS):
– Modules: alphabaghchal_mcts.c and alphabaghchal_mcts.h.
– Responsibilities: Implement MCTS logic: tree node creation, node expansion, selection (using UCB values), simulation (rollouts), and backpropagation of simulation results.
– This component is specific to the AlphaBaghChal enhanced version.
e. Training and Self-play:
– Modules: Functions such as train_against_random(), play_random_game(), and learn_from_game() found in main.c/alphabaghchal.c.
– Responsibilities: Updating the neural network based on game outcomes, reporting training progress and win/loss statistics.

##### How Components Interact
- The UI/Game Engine component invokes the Neural Network Engine when an AI move (tiger’s move) is needed.
- The Neural Network Engine may either run on the CPU or use CUDA Accelerated functions, so show a dependency from game logic to both the CUDA kernels and CPU-based neural network modules.

##### Architectural Patterns and Design Principles to Highlight
- Separation of Concerns: Different modules are responsible for user interaction (UI/game loop), AI decision making (neural network and MCTS), and hardware acceleration (CUDA kernels).
- Hybrid Execution: Explain that the system supports both CPU and GPU (CUDA) paths for neural network computations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CPU Variant Subgraph
    subgraph "CPU Variant"
        A1["Game Engine (main.c)"] 
        A2["Game Engine (baaghchaal.cpp)"]
    end

    %% MCTS Variant Subgraph
    subgraph "MCTS Variant"
        B1["Game Engine (alphabaghchal.c)"]
        B2["Game Engine Header (alphabaghchal.h)"]
    end

    %% CUDA Acceleration Subgraph
    subgraph "CUDA Acceleration"
        C1["CUDA Kernels (cuda_kernels.cu)"]
        C2["CUDA Kernels (alphabaghchal_cuda.cu)"]
    end

    %% MCTS Module Subgraph
    subgraph "MCTS Module"
        D1["MCTS Implementation (alphabaghchal_mcts.c)"]
        D2["MCTS Header (alphabaghchal_mcts.h)"]
    end

    %% Common Components
    E["Neural Network Engine"]
    F["Training & Self-play"]

    %% Connections from Game Engine to Neural Network Engine
    A1 -->|"request move"| E
    A2 -->|"request move"| E
    B1 -->|"request move"| E
    B2 -->|"request move"| E

    %% Training updates the Neural Network Engine
    F -->|"update NN"| E

    %% Neural Network Engine uses CUDA Acceleration
    E -->|"GPU acceleration"| C1
    E -->|"GPU acceleration"| C2

    %% MCTS Variant invokes MCTS Module and then uses NN for evaluation
    B1 -->|"MCTS decision"| D1
    B2 -->|"MCTS decision"| D2
    D1 -->|"evaluate state"| E
    D2 -->|"evaluate state"| E

    %% Neural Network Engine returns the computed move back to Game Engine
    E -->|"decision move"| A1
    E -->|"decision move"| B1

    %% Click events for component mapping
    click A1 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/main.c"
    click A2 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/baaghchaal.cpp"
    click B1 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/AlphaBaghChal/alphabaghchal.c"
    click B2 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/AlphaBaghChal/alphabaghchal.h"
    click C1 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/cuda_kernels.cu"
    click C2 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/AlphaBaghChal/alphabaghchal_cuda.cu"
    click D1 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/AlphaBaghChal/alphabaghchal_mcts.c"
    click D2 "https://github.com/dhakalnirajan/baghchal-rl/blob/main/AlphaBaghChal/alphabaghchal_mcts.h"

    %% Styles for components
    classDef cpu fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef gpu fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef mcts fill:#ffcccb,stroke:#000,stroke-width:1px;
    classDef ui fill:#f0e68c,stroke:#000,stroke-width:1px;
    classDef nn fill:#dda0dd,stroke:#000,stroke-width:1px;

    %% Assigning styles
    class A1,A2,F cpu;
    class B1,B2 mcts;
    class A1,A2,B1,B2 ui;
    class C1,C2 gpu;
    class D1,D2 mcts;
    class E nn;
```
