# cs10101/snake_ai_game architecture

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

- Interactive diagram: https://gitdiagram.com/cs10101/snake_ai_game
- Repository: https://github.com/cs10101/snake_ai_game

## Overview

AI Snake is a Deep Q-Learning application: its training loop observes the Snake environment, chooses and applies actions, learns from rewards and replayed experience, and tracks performance. The README also documents checkpoint resume/save and finite or indefinite training. The excerpts establish the main calls and model/plot logic, but omit parts of agent.py; uncertain internal wiring is not shown.

Main entry points: [`agent.py`](https://github.com/cs10101/snake_ai_game/blob/main/agent.py) (CLI and loop), [`game.py`](https://github.com/cs10101/snake_ai_game/blob/main/game.py) (Game step), [`model.py`](https://github.com/cs10101/snake_ai_game/blob/main/model.py) (Q trainer), [`helper.py`](https://github.com/cs10101/snake_ai_game/blob/main/helper.py) (Training plots)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Training runtime"]
  node_entry["CLI and loop<br/>[agent.py]"]
  node_state["State encoding<br/>[agent.py]"]
  node_policy["Action policy<br/>[agent.py]"]
end

subgraph group_environment["Snake environment"]
  node_game["Game step<br/>[game.py]"]
  node_world["Game state and rules<br/>[game.py]"]
end

subgraph group_learning["Q-learning"]
  node_memory["Replay memory<br/>[agent.py]"]
  node_network["Q network<br/>[model.py]"]
  node_trainer["Q trainer<br/>[model.py]"]
end

subgraph group_results["Persistence and results"]
  node_checkpoints["Model checkpoints"]
  node_plotter["Training plots<br/>[helper.py]"]
  node_outputs["Final graph"]
end

node_user(("Trainer"))

node_user -->|"starts training"| node_entry
node_entry -->|"requests observation"| node_state
node_state -->|"reads game state"| node_world
node_state -->|"checks collision"| node_world
node_entry -->|"requests action"| node_policy
node_policy -->|"predicts Q-values"| node_network
node_entry -->|"applies action"| node_game
node_game -->|"updates state"| node_world
node_game -->|"returns reward and score"| node_entry
node_entry -->|"stores experience"| node_memory
node_entry -->|"trains on step"| node_trainer
node_entry -->|"samples batches"| node_memory
node_entry -->|"trains batches"| node_trainer
node_trainer -->|"updates weights"| node_network
node_entry -->|"loads and saves model"| node_checkpoints
node_entry -->|"plots scores"| node_plotter
node_entry -->|"saves final graph"| node_outputs

click node_entry "https://github.com/cs10101/snake_ai_game/blob/main/agent.py"
click node_state "https://github.com/cs10101/snake_ai_game/blob/main/agent.py"
click node_policy "https://github.com/cs10101/snake_ai_game/blob/main/agent.py"
click node_memory "https://github.com/cs10101/snake_ai_game/blob/main/agent.py"
click node_game "https://github.com/cs10101/snake_ai_game/blob/main/game.py"
click node_world "https://github.com/cs10101/snake_ai_game/blob/main/game.py"
click node_network "https://github.com/cs10101/snake_ai_game/blob/main/model.py"
click node_trainer "https://github.com/cs10101/snake_ai_game/blob/main/model.py"
click node_plotter "https://github.com/cs10101/snake_ai_game/blob/main/helper.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_entry,node_state,node_policy toneBlue
class node_game,node_world toneAmber
class node_memory,node_network,node_trainer toneMint
class node_checkpoints,node_plotter,node_outputs toneRose
class node_user toneIndigo
```

## Components

### Training runtime

- [CLI and loop](https://github.com/cs10101/snake_ai_game/blob/main/agent.py): `agent.py`
- [State encoding](https://github.com/cs10101/snake_ai_game/blob/main/agent.py): `agent.py`
- [Action policy](https://github.com/cs10101/snake_ai_game/blob/main/agent.py): `agent.py`

### Snake environment

- [Game step](https://github.com/cs10101/snake_ai_game/blob/main/game.py): `game.py`
- [Game state and rules](https://github.com/cs10101/snake_ai_game/blob/main/game.py): `game.py`

### Q-learning

- [Replay memory](https://github.com/cs10101/snake_ai_game/blob/main/agent.py): `agent.py`
- [Q network](https://github.com/cs10101/snake_ai_game/blob/main/model.py): `model.py`
- [Q trainer](https://github.com/cs10101/snake_ai_game/blob/main/model.py): `model.py`

### Persistence and results

- **Model checkpoints**
- [Training plots](https://github.com/cs10101/snake_ai_game/blob/main/helper.py): `helper.py`
- **Final graph**

### Other components

- **Trainer**

## Connections

- Trainer → CLI and loop: starts training
- CLI and loop → State encoding: requests observation
- State encoding → Game state and rules: reads game state
- State encoding → Game state and rules: checks collision
- CLI and loop → Action policy: requests action
- Action policy → Q network: predicts Q-values
- CLI and loop → Game step: applies action
- Game step → Game state and rules: updates state
- Game step → CLI and loop: returns reward and score
- CLI and loop → Replay memory: stores experience
- CLI and loop → Q trainer: trains on step
- CLI and loop → Replay memory: samples batches
- CLI and loop → Q trainer: trains batches
- Q trainer → Q network: updates weights
- CLI and loop → Model checkpoints: loads and saves model
- CLI and loop → Training plots: plots scores
- CLI and loop → Final graph: saves final graph