# leilibrk/pacman-ai-project architecture

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

- Interactive diagram: https://gitdiagram.com/leilibrk/pacman-ai-project
- Repository: https://github.com/leilibrk/pacman-ai-project

## Overview

##### Main components
- Game Engine & UI: This includes files such as pacman.py, game.py, graphicsDisplay.py, textDisplay.py, and graphicsUtils.py. This component handles the game loop, rendering, input from the user (keyboardAgents.py), and overall game state.
- Layout Management: With a dedicated “layouts” directory (and files like layout.py), this component manages maze configurations and level representations.
- AI Algorithms & Agents: Several modules implement the algorithms (search.py, searchAgents.py, pacmanAgents.py, ghostAgents.py) that control Pac-Man’s decision-making. Illustrate both uninformed (DFS, BFS, UCS) and informed (A*, Expectimax, Minimax) as separate algorithmic sub-components.
- Testing & Grading Framework: There are numerous test cases in the test_cases directory and grading utilities (autograder.py, grading.py, testParser.py, testClasses.py). This reflects an integration/test harness module.
- Utility Modules: Extra helper modules such as util.py and projectParams.py should also be represented, as they provide cross-cutting functionality.

##### Relationships and interactions
- How the Game Engine sends the current game state (including maze layout, score, ghost positions, etc.) to the AI Algorithms.
- That each algorithm (DFS, BFS, UCS, A*, Minimax with Alpha-Beta, Expectimax, and Q-learning in the later phase) outputs an action which feeds back into the game engine, affecting Pac-Man’s movement.
- That the testing framework automatically runs a suite of tests on these algorithms, ensuring results and performance metrics.

##### Architectural patterns and design principles
- Layer Separation: Separate the presentation/UI layer (graphics and keyboard agents) from the game logic and AI decision-making layer.
- Modular Design: Emphasize that each algorithm is implemented in its own module (such as searchAgents.py) so that they can be “swapped” or compared (this is also clear from the test cases that compare algorithm performance).
- Data Flow and Reaction: Since you mentioned “show what the algorithm react with,” add explicit reaction pathways – for example, illustrate that when the game state changes (e.g., a ghost moves), this state is passed to one or more AI algorithm modules, which then compute a new action that “reacts” to the changed environment.

##### Technologies and Key Elements
- Python is the main technology, so consider highlighting Python’s standard library usage (e.g., __pycache__ and common modules for testing and configuration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Game Engine & UI
    subgraph "Game Engine & UI"
        subgraph "Game Loop & Rendering"
            GE1("pacman.py"):::game
            GE2("game.py"):::game
        end
        subgraph "Display Modules"
            GE3("graphicsDisplay.py"):::game
            GE4("graphicsUtils.py"):::game
            GE5("textDisplay.py"):::game
        end
        subgraph "User Input"
            GE6("keyboardAgents.py"):::game
        end
    end

    %% Layout Management
    subgraph "Layout Management"
        LM1("layout.py"):::layout
        LM2("layouts/"):::layout
    end

    %% AI Algorithms & Agents
    subgraph "AI Algorithms & Agents"
        AI1("search.py"):::ai
        AI2("searchAgents.py"):::ai
        AI3("pacmanAgents.py"):::ai
        AI4("ghostAgents.py"):::ai
        subgraph "Algorithm Reaction Flow"
            AF1("Game State Input"):::ai
            AF2("Action Output"):::ai
        end
    end

    %% Testing & Grading Framework
    subgraph "Testing & Grading Framework"
        T1("autograder.py"):::test
        T2("grading.py"):::test
        T3("testParser.py"):::test
        T4("testClasses.py"):::test
        T5("searchTestClasses.py"):::test
        T6("test_cases/"):::test
    end

    %% Utility Modules
    subgraph "Utility Modules"
        U1("util.py"):::util
        U2("projectParams.py"):::util
    end

    %% Data Flow: User Input to Game Engine
    GE6 -->|"input"| GE1

    %% Data Flow: Game Engine sends state to AI Reaction Flow
    GE1 -->|"state_update"| AF1

    %% Data Flow: AI Reaction Flow sends action back to Game Engine
    AF2 -->|"action_command"| GE1

    %% Layout Management influence on Game Engine and AI Reaction
    LM1 -->|"maze_layout"| GE1
    LM2 -->|"layouts"| GE1
    LM1 -->|"map_info"| AF1
    LM2 -->|"map_info"| AF1

    %% Testing Framework interactions with AI Algorithms
    T6 -->|"test_inputs"| AF1
    AF2 -->|"verification"| T6
    T1 -->|"validate"| AI1
    T1 -->|"validate"| AI2
    T1 -->|"validate"| AI3
    T1 -->|"validate"| AI4
    T4 -->|"tests_reaction"| AF1

    %% AI Algorithms reacting within Reaction Flow
    AI1 -->|"reacts"| AF1
    AI2 -->|"reacts"| AF1
    AI3 -->|"reacts"| AF1
    AI4 -->|"reacts"| AF1

    %% Utility Modules usage (dashed connections)
    U1 ---|"common_functions"| GE1
    U1 ---|"common_functions"| AI1
    U2 ---|"params"| GE1
    U2 ---|"params"| AI1

    %% Click Events for Game Engine & UI
    click GE1 "https://github.com/leilibrk/pacman-ai-project/blob/master/pacman.py"
    click GE2 "https://github.com/leilibrk/pacman-ai-project/blob/master/game.py"
    click GE3 "https://github.com/leilibrk/pacman-ai-project/blob/master/graphicsDisplay.py"
    click GE4 "https://github.com/leilibrk/pacman-ai-project/blob/master/graphicsUtils.py"
    click GE5 "https://github.com/leilibrk/pacman-ai-project/blob/master/textDisplay.py"
    click GE6 "https://github.com/leilibrk/pacman-ai-project/blob/master/keyboardAgents.py"

    %% Click Events for Layout Management
    click LM1 "https://github.com/leilibrk/pacman-ai-project/blob/master/layout.py"
    click LM2 "https://github.com/leilibrk/pacman-ai-project/tree/master/layouts/"

    %% Click Events for AI Algorithms & Agents
    click AI1 "https://github.com/leilibrk/pacman-ai-project/blob/master/search.py"
    click AI2 "https://github.com/leilibrk/pacman-ai-project/blob/master/searchAgents.py"
    click AI3 "https://github.com/leilibrk/pacman-ai-project/blob/master/pacmanAgents.py"
    click AI4 "https://github.com/leilibrk/pacman-ai-project/blob/master/ghostAgents.py"

    %% Click Events for Testing & Grading Framework
    click T1 "https://github.com/leilibrk/pacman-ai-project/blob/master/autograder.py"
    click T2 "https://github.com/leilibrk/pacman-ai-project/blob/master/grading.py"
    click T3 "https://github.com/leilibrk/pacman-ai-project/blob/master/testParser.py"
    click T4 "https://github.com/leilibrk/pacman-ai-project/blob/master/testClasses.py"
    click T5 "https://github.com/leilibrk/pacman-ai-project/blob/master/searchTestClasses.py"
    click T6 "https://github.com/leilibrk/pacman-ai-project/tree/master/test_cases/"

    %% Click Events for Utility Modules
    click U1 "https://github.com/leilibrk/pacman-ai-project/blob/master/util.py"
    click U2 "https://github.com/leilibrk/pacman-ai-project/blob/master/projectParams.py"

classDef game fill:#ADD8E6,stroke:#000,stroke-width:1px;
classDef layout fill:#90EE90,stroke:#000,stroke-width:1px;
classDef ai fill:#FFB6C1,stroke:#000,stroke-width:1px;
classDef test fill:#FFFACD,stroke:#000,stroke-width:1px;
classDef util fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
