# bhavya0304/snakeai architecture

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

- Interactive diagram: https://gitdiagram.com/bhavya0304/snakeai
- Repository: https://github.com/bhavya0304/snakeai

## Overview

##### Project type and purpose
- This is a research/demo project that implements Deep Q-Learning to train an AI agent on the Snake game.
- Key goal: demonstrate RL training loop, environment interaction, and model persistence/visualization.

##### File structure
Top-level:
- AI.py, SnakeAI.py, network.py, app.py – standalone scripts for experiments or launching games.
- requirements.txt – lists Python dependencies (e.g., pygame, torch).
- research/Reinforcement-Learning – background notes or references.
Core module: SnakeAI_Final/
- agent.py – DQN agent logic (action selection, ε-greedy policy, training loop).
- game.py – custom Snake environment built on pygame (state, reward, reset, step).
- helper.py – utility functions (e.g., state preprocessing, reward shaping).
- model.py – neural network definition (PyTorch module) and model persistence (load/save).
- model/model.pth – checkpoint of trained network.

##### Extract architecture insights from the README
- Components described: Environment, State Representation, Action Space, Reward Function, DQN, Experience Replay, Target Network.
- Training flow steps and dataflow between agent and environment.

##### Main components
a. Snake Game Environment (game.py + Pygame)
b. Replay Buffer (experience storage – implemented in agent.py/helper)
c. Deep Q-Network (model.py + network.py)
d. Target Network (a copy of the DQN, updated periodically)
e. Training Loop (agent.py orchestrates episodes & optimization)
f. Model Persistence (saving/loading model.pth)
g. Visualization / Demo App (app.py or SnakeAI.py for real-time display)

##### Relationships and dataflow
1. Training Loop triggers:
– “Reset Environment” → game.py
– “Observe State” ← returns state
– “Select Action (ε-greedy)” → agent.py
– “Step Environment(Action)” → game.py → returns next state, reward, done flag
– “Store Experience” → Replay Buffer
– “Sample Mini-batch” → Replay Buffer → feed to DQN
– “Compute Target Q-values” (using Target Network)
– “Optimize DQN” (backprop in model.py)
2. “Update Target Network” periodically (agent.py)
3. “Save Model Checkpoint” → disk (model/model.pth)
4. “Visualization” (app.py) reads model and runs live demo

##### Architectural patterns & principles
- Separation of Concerns:
- Environment vs. Agent vs. Network definition
- Replay Buffer decouples data collection from learning
- Modular Design: each Python module has a clear responsibility
- Pipeline Pattern: data flows in a loop (state → action → reward → learning)

##### Essential elements
- Component labels matching project files.
- Arrowheads showing flow direction.
- A note on the ε-greedy policy and target network update frequency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    subgraph "Core RL Pipeline"
        Env["Snake Game Environment"]:::code
        Agent["Training Loop & ε-greedy Policy"]:::code
        ReplayBuffer["Experience Replay"]:::datastore
        DQN["Deep Q-Network"]:::code
        TargetNet["Target Network"]:::code
        Persistence["Model Persistence"]:::code
        ModelFile["model.pth"]:::datastore
    end

    %% Utilities
    subgraph "Utilities"
        Utils["Utility Functions"]:::util
        AuxNet["Auxiliary Network Definitions"]:::code
    end

    %% Visualization & Scripts
    subgraph "Visualization & Scripts"
        App["Visualization Demo"]:::script
        AIexp["Standalone Experiment Scripts"]:::script
    end

    %% External Frameworks
    subgraph "External Frameworks"
        Pygame["Pygame"]:::framework
        PyTorch["PyTorch"]:::framework
    end

    %% Other Resources
    subgraph "Other Resources"
        Req["requirements.txt"]:::script
        Research["Research Notes"]:::script
    end

    %% Connections
    Env -->|"s"| Agent
    Agent -->|"a"| Env
    Env -->|"r, s' "| Agent
    Agent -->|"store s,a,r,s'"| ReplayBuffer
    ReplayBuffer -->|"sample batch"| DQN
    DQN -->|"q values"| Agent
    Agent -->|"update weights"| DQN
    Agent -->|"periodic update"| TargetNet
    DQN -->|"save/load"| Persistence
    Persistence -->|"checkpoint"| ModelFile

    Utils --> Agent
    Utils --> DQN
    AuxNet --> DQN
    AuxNet --> TargetNet

    App -->|"load policy"| DQN
    App -->|"load policy"| TargetNet
    AIexp --> Agent
    AIexp --> App

    Pygame --> Env
    PyTorch --> DQN
    PyTorch --> TargetNet

    Req -.-> Env
    Req -.-> Agent
    Req -.-> DQN
    Req -.-> App

    Research -.-> Env
    Research -.-> Agent
    Research -.-> DQN

    %% Click Events
    click Env "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/game.py"
    click ReplayBuffer "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/agent.py"
    click DQN "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/model.py"
    click AuxNet "https://github.com/bhavya0304/snakeai/blob/main/network.py"
    click TargetNet "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/agent.py"
    click Agent "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/agent.py"
    click Persistence "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/model.py"
    click ModelFile "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/model/model.pth"
    click Utils "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI_Final/helper.py"
    click App "https://github.com/bhavya0304/snakeai/blob/main/app.py"
    click AIexp "https://github.com/bhavya0304/snakeai/blob/main/AI.py"
    click AIexp "https://github.com/bhavya0304/snakeai/blob/main/SnakeAI.py"
    click Req "https://github.com/bhavya0304/snakeai/blob/main/requirements.txt"
    click Research "https://github.com/bhavya0304/snakeai/tree/main/research/Reinforcement-Learning"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef datastore fill:#90EE90,stroke:#000,stroke-width:1px
    classDef framework fill:#FFA500,stroke:#000,stroke-width:1px
    classDef util fill:#D8BFD8,stroke:#000,stroke-width:1px
    classDef script fill:#87CEEB,stroke:#000,stroke-width:1px
```
