# wajih1234/snake-game-ai architecture

> Architecture diagram of the GitHub repository wajih1234/snake-game-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wajih1234/snake-game-ai
- Repository: https://github.com/wajih1234/snake-game-ai

## Overview

This is a Snake game agent trained with deep Q-learning. The training loop observes the game, selects and applies actions, learns from rewards and next states, and tracks scores. The graph separates game simulation, agent behavior and replay memory, and model training and persistence. Calls within these components are supported by the sampled files; the repository provides no README, so broader product capabilities are not documented.

Main entry points: [`agent.py`](https://github.com/wajih1234/snake-game-ai/blob/main/agent.py) (Training Loop), [`game.py`](https://github.com/wajih1234/snake-game-ai/blob/main/game.py) (Game Environment), [`model.py`](https://github.com/wajih1234/snake-game-ai/blob/main/model.py) (Q Network), [`helper.py`](https://github.com/wajih1234/snake-game-ai/blob/main/helper.py) (Score Plotting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training and Agent"]
  node_runner["Training Loop<br/>[agent.py]"]
  node_agent["Agent Policy<br/>[agent.py]"]
  node_memory["Replay Memory<br/>[agent.py]"]
  node_plot["Score Plotting<br/>[helper.py]"]
end

subgraph group_game["Snake Game"]
  node_environment["Game Environment<br/>[game.py]"]
  node_movement["Snake Movement<br/>[game.py]"]
  node_rules["Collision and Food<br/>[game.py]"]
  node_display["Game Display<br/>[game.py]"]
end

subgraph group_learning["Q Learning"]
  node_network["Q Network<br/>[model.py]"]
  node_trainer["Q Trainer<br/>[model.py]"]
  node_checkpoint["Model Checkpoint<br/>[model.py]"]
end

node_runner -->|"uses policy"| node_agent
node_runner -->|"steps game"| node_environment
node_runner -->|"stores transitions"| node_memory
node_runner -->|"trains model"| node_trainer
node_runner -->|"plots scores"| node_plot
node_agent -->|"reads state"| node_environment
node_agent -->|"predicts action"| node_network
node_agent -->|"trains step"| node_trainer
node_environment -->|"updates position"| node_movement
node_environment -->|"checks outcome"| node_rules
node_environment -->|"updates display"| node_display
node_trainer -->|"evaluates values"| node_network
node_network -->|"saves weights"| node_checkpoint

click node_runner "https://github.com/wajih1234/snake-game-ai/blob/main/agent.py"
click node_agent "https://github.com/wajih1234/snake-game-ai/blob/main/agent.py"
click node_memory "https://github.com/wajih1234/snake-game-ai/blob/main/agent.py"
click node_plot "https://github.com/wajih1234/snake-game-ai/blob/main/helper.py"
click node_environment "https://github.com/wajih1234/snake-game-ai/blob/main/game.py"
click node_movement "https://github.com/wajih1234/snake-game-ai/blob/main/game.py"
click node_rules "https://github.com/wajih1234/snake-game-ai/blob/main/game.py"
click node_display "https://github.com/wajih1234/snake-game-ai/blob/main/game.py"
click node_network "https://github.com/wajih1234/snake-game-ai/blob/main/model.py"
click node_trainer "https://github.com/wajih1234/snake-game-ai/blob/main/model.py"
click node_checkpoint "https://github.com/wajih1234/snake-game-ai/blob/main/model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_agent,node_memory,node_plot toneBlue
class node_environment,node_movement,node_rules,node_display toneAmber
class node_network,node_trainer,node_checkpoint toneMint
```

## Components

### Training and Agent

- [Training Loop](https://github.com/wajih1234/snake-game-ai/blob/main/agent.py): `agent.py`
- [Agent Policy](https://github.com/wajih1234/snake-game-ai/blob/main/agent.py): `agent.py`
- [Replay Memory](https://github.com/wajih1234/snake-game-ai/blob/main/agent.py): `agent.py`
- [Score Plotting](https://github.com/wajih1234/snake-game-ai/blob/main/helper.py): `helper.py`

### Snake Game

- [Game Environment](https://github.com/wajih1234/snake-game-ai/blob/main/game.py): `game.py`
- [Snake Movement](https://github.com/wajih1234/snake-game-ai/blob/main/game.py): `game.py`
- [Collision and Food](https://github.com/wajih1234/snake-game-ai/blob/main/game.py): `game.py`
- [Game Display](https://github.com/wajih1234/snake-game-ai/blob/main/game.py): `game.py`

### Q Learning

- [Q Network](https://github.com/wajih1234/snake-game-ai/blob/main/model.py): `model.py`
- [Q Trainer](https://github.com/wajih1234/snake-game-ai/blob/main/model.py): `model.py`
- [Model Checkpoint](https://github.com/wajih1234/snake-game-ai/blob/main/model.py): `model.py`

## Connections

- Training Loop → Agent Policy: uses policy (evidence: `agent.py`)
- Training Loop → Game Environment: steps game (evidence: `agent.py`)
- Training Loop → Replay Memory: stores transitions (evidence: `agent.py`)
- Training Loop → Q Trainer: trains model (evidence: `agent.py`)
- Training Loop → Score Plotting: plots scores (evidence: `agent.py`)
- Agent Policy → Game Environment: reads state (evidence: `agent.py`)
- Agent Policy → Q Network: predicts action (evidence: `agent.py`)
- Agent Policy → Q Trainer: trains step (evidence: `agent.py`)
- Game Environment → Snake Movement: updates position (evidence: `game.py`)
- Game Environment → Collision and Food: checks outcome (evidence: `game.py`)
- Game Environment → Game Display: updates display (evidence: `game.py`)
- Q Trainer → Q Network: evaluates values (evidence: `model.py`)
- Q Network → Model Checkpoint: saves weights (evidence: `model.py`)
