# mapel0x/snake-ai-rl architecture

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

- Interactive diagram: https://gitdiagram.com/mapel0x/snake-ai-rl
- Repository: https://github.com/mapel0x/snake-ai-rl

## Overview

This is a Snake game-playing and training application: `src/main.py` runs training or greedy play, while the DQN learns from environment transitions and can be resumed from saved weights. The graph covers game rules, learning, visualization, and logged results. Training data and episode histories are written to CSV; plots are generated from histories. Headless training is supported. The README documents these capabilities, but some `main.py` calls are in omitted excerpts, so those relationships are cited to the README rather than inferred from module co-imports.

Main entry points: [`src/main.py`](https://github.com/mapel0x/snake-ai-rl/blob/main/src/main.py) (Train / play), [`src/agent.py`](https://github.com/mapel0x/snake-ai-rl/blob/main/src/agent.py) (DQN agent), [`src/dataset_logger.py`](https://github.com/mapel0x/snake-ai-rl/blob/main/src/dataset_logger.py) (CSV logging), [`src/environment.py`](https://github.com/mapel0x/snake-ai-rl/blob/main/src/environment.py) (State and rewards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run orchestration"]
  node_entry["Train / play<br/>[main.py]"]
  node_settings["Game and RL config<br/>[config.py]"]
end

subgraph group_game["Snake environment"]
  node_environment["State and rewards<br/>[environment.py]"]
  node_snake["Snake movement<br/>[snake.py]"]
  node_food["Food spawning<br/>[food.py]"]
  node_renderer["Pygame renderer<br/>[game.py]"]
end

subgraph group_learn["DQN learning"]
  node_agent["DQN agent<br/>[agent.py]"]
  node_network["Q networks<br/>[model.py]"]
  node_replay["Experience replay<br/>[replay_memory.py]"]
  node_trainer["Q-learning optimizer<br/>[trainer.py]"]
  node_checkpoint["Model weights<br/>[snake_model.pth]"]
end

subgraph group_results["Logs and evaluation"]
  node_logger["CSV logging<br/>[dataset_logger.py]"]
  node_steps["Step dataset<br/>[snake_dataset.csv]"]
  node_rewardhistory["Reward history<br/>[reward_history.csv]"]
  node_scorehistory["Score history<br/>[score_history.csv]"]
  node_losshistory["Loss history<br/>[loss_history.csv]"]
  node_plots["Training plots"]
end

node_user(("User"))

node_user -->|"starts"| node_entry
node_entry -->|"runs episodes"| node_environment
node_entry -->|"selects actions"| node_agent
node_entry -->|"renders play"| node_renderer
node_entry -->|"logs steps"| node_logger
node_entry -->|"uses parameters"| node_settings
node_environment -->|"moves and checks"| node_snake
node_environment -->|"spawns and reads"| node_food
node_renderer -->|"draws"| node_snake
node_renderer -->|"draws"| node_food
node_agent -->|"predicts with"| node_network
node_agent -->|"stores transitions"| node_replay
node_agent -->|"delegates learning"| node_trainer
node_trainer -->|"samples batches"| node_replay
node_trainer -->|"optimizes policy"| node_network
node_agent -->|"saves and loads"| node_checkpoint
node_logger -->|"appends transitions"| node_steps
node_logger -->|"appends summaries"| node_rewardhistory
node_logger -->|"appends summaries"| node_scorehistory
node_entry -->|"reads for plots"| node_rewardhistory
node_entry -->|"reads for plots"| node_scorehistory
node_entry -->|"reads for plots"| node_losshistory
node_entry -->|"writes charts"| node_plots
node_entry -->|"resumes training"| node_checkpoint

click node_entry "https://github.com/mapel0x/snake-ai-rl/blob/main/src/main.py"
click node_settings "https://github.com/mapel0x/snake-ai-rl/blob/main/src/config.py"
click node_environment "https://github.com/mapel0x/snake-ai-rl/blob/main/src/environment.py"
click node_snake "https://github.com/mapel0x/snake-ai-rl/blob/main/src/snake.py"
click node_food "https://github.com/mapel0x/snake-ai-rl/blob/main/src/food.py"
click node_renderer "https://github.com/mapel0x/snake-ai-rl/blob/main/src/game.py"
click node_agent "https://github.com/mapel0x/snake-ai-rl/blob/main/src/agent.py"
click node_network "https://github.com/mapel0x/snake-ai-rl/blob/main/src/model.py"
click node_replay "https://github.com/mapel0x/snake-ai-rl/blob/main/src/replay_memory.py"
click node_trainer "https://github.com/mapel0x/snake-ai-rl/blob/main/src/trainer.py"
click node_checkpoint "https://github.com/mapel0x/snake-ai-rl/blob/main/models/snake_model.pth"
click node_logger "https://github.com/mapel0x/snake-ai-rl/blob/main/src/dataset_logger.py"
click node_steps "https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/snake_dataset.csv"
click node_rewardhistory "https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/reward_history.csv"
click node_scorehistory "https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/score_history.csv"
click node_losshistory "https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/loss_history.csv"
click node_plots "https://github.com/mapel0x/snake-ai-rl/tree/main/graphs"

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_settings,node_user toneBlue
class node_environment,node_snake,node_food,node_renderer toneAmber
class node_agent,node_network,node_replay,node_trainer,node_checkpoint toneMint
class node_logger,node_steps,node_rewardhistory,node_scorehistory,node_losshistory,node_plots toneRose
```

## Components

### Run orchestration

- [Train / play](https://github.com/mapel0x/snake-ai-rl/blob/main/src/main.py): `src/main.py`
- [Game and RL config](https://github.com/mapel0x/snake-ai-rl/blob/main/src/config.py): `src/config.py`

### Snake environment

- [State and rewards](https://github.com/mapel0x/snake-ai-rl/blob/main/src/environment.py): `src/environment.py`
- [Snake movement](https://github.com/mapel0x/snake-ai-rl/blob/main/src/snake.py): `src/snake.py`
- [Food spawning](https://github.com/mapel0x/snake-ai-rl/blob/main/src/food.py): `src/food.py`
- [Pygame renderer](https://github.com/mapel0x/snake-ai-rl/blob/main/src/game.py): `src/game.py`

### DQN learning

- [DQN agent](https://github.com/mapel0x/snake-ai-rl/blob/main/src/agent.py): `src/agent.py`
- [Q networks](https://github.com/mapel0x/snake-ai-rl/blob/main/src/model.py): `src/model.py`
- [Experience replay](https://github.com/mapel0x/snake-ai-rl/blob/main/src/replay_memory.py): `src/replay_memory.py`
- [Q-learning optimizer](https://github.com/mapel0x/snake-ai-rl/blob/main/src/trainer.py): `src/trainer.py`
- [Model weights](https://github.com/mapel0x/snake-ai-rl/blob/main/models/snake_model.pth): `models/snake_model.pth`

### Logs and evaluation

- [CSV logging](https://github.com/mapel0x/snake-ai-rl/blob/main/src/dataset_logger.py): `src/dataset_logger.py`
- [Step dataset](https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/snake_dataset.csv): `dataset/snake_dataset.csv`
- [Reward history](https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/reward_history.csv): `dataset/reward_history.csv`
- [Score history](https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/score_history.csv): `dataset/score_history.csv`
- [Loss history](https://github.com/mapel0x/snake-ai-rl/blob/main/dataset/loss_history.csv): `dataset/loss_history.csv`
- [Training plots](https://github.com/mapel0x/snake-ai-rl/tree/main/graphs): `graphs`

### Other components

- **User**

## Connections

- User → Train / play: starts (evidence: `README.md`)
- Train / play → State and rewards: runs episodes (evidence: `src/main.py`)
- Train / play → DQN agent: selects actions (evidence: `src/main.py`)
- Train / play → Pygame renderer: renders play (evidence: `src/main.py`)
- Train / play → CSV logging: logs steps (evidence: `src/main.py`)
- Train / play → Game and RL config: uses parameters (evidence: `src/main.py`)
- State and rewards → Snake movement: moves and checks (evidence: `src/environment.py`)
- State and rewards → Food spawning: spawns and reads (evidence: `src/environment.py`)
- Pygame renderer → Snake movement: draws (evidence: `src/game.py`)
- Pygame renderer → Food spawning: draws (evidence: `src/game.py`)
- DQN agent → Q networks: predicts with (evidence: `src/agent.py`)
- DQN agent → Experience replay: stores transitions (evidence: `src/agent.py`)
- DQN agent → Q-learning optimizer: delegates learning (evidence: `src/agent.py`)
- Q-learning optimizer → Experience replay: samples batches (evidence: `src/trainer.py`)
- Q-learning optimizer → Q networks: optimizes policy (evidence: `src/trainer.py`)
- DQN agent → Model weights: saves and loads (evidence: `src/agent.py`)
- CSV logging → Step dataset: appends transitions (evidence: `src/dataset_logger.py`)
- CSV logging → Reward history: appends summaries (evidence: `src/dataset_logger.py`)
- CSV logging → Score history: appends summaries (evidence: `src/dataset_logger.py`)
- Train / play → Reward history: reads for plots (evidence: `src/main.py`)
- Train / play → Score history: reads for plots (evidence: `src/main.py`)
- Train / play → Loss history: reads for plots (evidence: `src/main.py`)
- Train / play → Training plots: writes charts (evidence: `src/main.py`)
- Train / play → Model weights: resumes training (evidence: `README.md`)
