# trongdung143/ai-search-algorithms architecture

> Architecture diagram of the GitHub repository trongdung143/ai-search-algorithms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trongdung143/ai-search-algorithms
- Repository: https://github.com/trongdung143/ai-search-algorithms

## Overview

##### Project type and purpose
- This is a standalone, educational desktop application (built in Python) that visualizes various pathfinding algorithms in a maze-like environment.
- Users interact via a Pygame‐driven GUI to generate mazes and watch algorithms (DFS, BFS, A*, etc.) explore and find paths.

##### File structure
- Top‐level files:
- main.py → the entry point, game loop, orchestrator
- test.py → unit tests for key modules
- requirements.txt → lists dependencies (pygame, numpy)
- README.md, FinalReport.docx → docs
- No separate frontend/backend: all logic, visualization, and control live in one monolithic Python codebase.
- External libraries: Pygame (UI/renderer), NumPy (grid matrix), built‐in Queue/PriorityQueue (algorithm support), Random/Copy (maze generation/state copying).

##### README for additional insights
- Confirms interactive GUI, custom‐map support, multiple algorithms, real‐time visualization.
- Mentions use cases: teaching, performance comparison.

##### Main components
a. UI Layer (Pygame Renderer & Event Handler)
- Handles drawing the maze grid, start/goal markers, walls, algorithm animation frames
- Captures user inputs (mouse clicks, key presses) for map creation, algorithm selection, start/stop
b. Controller / Orchestrator (main.py)
- Initializes the UI, grid model, algorithm modules
- Responds to UI events by delegating tasks (maze generation, pathfinding, reset)
- Manages the game loop (tick/update/render)
c. Maze Model & Generator
- Represents the grid as a 2D NumPy array or nested lists
- Provides APIs to add/remove walls, set start/goal, random maze generation
d. Pathfinding Algorithms Module
- Implements each algorithm (DFS, BFS, A*, UCS, Greedy, Hill Climbing, Beam) as separate functions or classes
- Uses shared data structures (Queue, PriorityQueue) for frontier management
- Returns the explored nodes sequence and the final path
e. Data Structures & Utilities
- PriorityQueue wrappers, Node/State representations, distance heuristics
- Random and copy utilities for state handling and maze gen
f. Test Suite (test.py)
- Contains unit tests for core logic (e.g., correctness of each algorithm, grid boundary checks)
g. Assets (images/)

##### Relationships and interactions
- UI Layer ←→ Controller: UI events → controller actions; controller → UI render commands
- Controller → Maze Model: invoke generation and modifications
- Controller → Pathfinding Module: pass the current maze state + start/goal → retrieve solution steps
- Pathfinding Module ← Data Structures & Utilities: queue operations, heuristic computations

##### Architectural patterns & design principles
- Model–View–Controller (MVC) style separation:
- Model = Maze Model + Algorithm state
- View = Pygame Renderer
- Controller = main.py event/game loop
- Single‐process, event‐driven architecture with clear separation of concerns
- Modular algorithm implementations for extensibility (easily add new pathfinders)

##### Technologies & frameworks
- Python 3.9+
- Pygame for UI/rendering/event loop
- NumPy for efficient grid handling
- Built‐in queues for BFS/UCS/A*
- Random, Copy for maze gen

##### Elements
- UI → Controller (user events)
- Controller → Model/Algorithms (invocations)
- Algorithms → Controller (results)
- Controller → UI (render commands)
- UI components (blue)
- Core logic components (green)
- Utilities/data structures (orange)
- Tests & assets (gray)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Interface"
        UI["UI Layer\n(Pygame Renderer & Event Handler)"]:::frontend
    end

    subgraph "Controller"
        Controller["Controller / Orchestrator\n(Game Loop, Event Dispatch)"]:::core
    end

    subgraph "Model"
        Model["Maze Model & Generator\n(Grid Representation, APIs)"]:::core
    end

    subgraph "Algorithms"
        Algorithms["Pathfinding Algorithms Module\n(DFS, BFS, A*, UCS, Greedy, Hill Climbing, Beam)\n+ NewAlgorithmPlugin"]:::core
    end

    subgraph "Utilities"
        Utils["Data Structures & Utilities\n(PriorityQueue Wrappers, Heuristics, Random/Copy)"]:::util
    end

    subgraph "Testing & Assets"
        Tests["Test Suite\n(Unit Tests for Algorithms & Grid)"]:::gray
        Assets["Assets\n(images/)"]:::gray
    end

    subgraph "Documentation & Configuration"
        Docs["Docs & Config\n(requirements.txt, README.md, FinalReport.docx, .gitignore)"]:::gray
    end

    UI -->|"user events"| Controller
    Controller -->|"invokeGeneration()/modifyModel()"| Model
    Controller -->|"runAlgorithm(maze, start, goal)"| Algorithms
    Algorithms -->|"results (explored nodes, path)"| Controller
    Controller -->|"drawGrid(gridState)"| UI
    Algorithms -->|"uses data structures & heuristics"| Utils
    Tests -->|"tests"| Model
    Tests -->|"tests"| Algorithms

    click UI "https://github.com/trongdung143/ai-search-algorithms/blob/main/main.py"
    click Controller "https://github.com/trongdung143/ai-search-algorithms/blob/main/main.py"
    click Model "https://github.com/trongdung143/ai-search-algorithms/blob/main/main.py"
    click Algorithms "https://github.com/trongdung143/ai-search-algorithms/blob/main/main.py"
    click Utils "https://github.com/trongdung143/ai-search-algorithms/blob/main/main.py"
    click Tests "https://github.com/trongdung143/ai-search-algorithms/blob/main/test.py"
    click Assets "https://github.com/trongdung143/ai-search-algorithms/tree/main/images/"
    click Docs "https://github.com/trongdung143/ai-search-algorithms/blob/main/requirements.txt"
    click Docs "https://github.com/trongdung143/ai-search-algorithms/blob/main/README.md"
    click Docs "https://github.com/trongdung143/ai-search-algorithms/blob/main/FinalReport.docx"
    click Docs "https://github.com/trongdung143/ai-search-algorithms/blob/main/.gitignore"

    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef util fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef gray fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
