# muzilyag/snake_ai architecture

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

- Interactive diagram: https://gitdiagram.com/muzilyag/snake_ai
- Repository: https://github.com/muzilyag/snake_ai

## Overview

This is a multi-agent snake reinforcement-learning application: it runs parallel game environments, trains role-specific MAPPO agents, and offers live visualization, metrics, plotting, and checkpoints. The main loop coordinates environment setup, action selection, simulation, rollout collection, and training. The native engine separates simulation systems for physics, radar observations, and rewards. Source excerpts establish the main Python wiring and some native dependencies; the Python-to-native runtime connection and several unsampled subsystem details are not fully shown, so those links are omitted or marked unverified.

Main entry points: [`main.py`](https://github.com/muzilyag/snake_ai/blob/main/main.py) (Training loop), [`src/engine/vec_env.cpp`](https://github.com/muzilyag/snake_ai/blob/main/src/engine/vec_env.cpp) (Vector engine), [`src/agents/actor.py`](https://github.com/muzilyag/snake_ai/blob/main/src/agents/actor.py) (MAPPO agent), [`src/env/env_wrapper.py`](https://github.com/muzilyag/snake_ai/blob/main/src/env/env_wrapper.py) (Vector environment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run coordination"]
  node_main["Training loop<br/>[main.py]"]
  node_settings["Settings<br/>[config.py]"]
end

subgraph group_learning["MAPPO learning"]
  node_agent["MAPPO agent<br/>[actor.py]"]
  node_models["Actor-critic models<br/>[mappo_models.py]"]
  node_rollout["Rollout buffer<br/>[rollout.py]"]
  node_trainer["MAPPO trainer<br/>[mappo_trainer.py]"]
end

subgraph group_simulation["Game simulation"]
  node_environment["Vector environment<br/>[env_wrapper.py]"]
  node_entities["Snake entities<br/>[entity.py]"]
  node_binding["Python binding<br/>[pybind_module.cpp]"]
  node_engine["Vector engine<br/>[vec_env.cpp]"]
  node_physics["Physics system<br/>[physics.cpp]"]
  node_radar["Radar system<br/>[radar.cpp]"]
  node_rewards["Reward system<br/>[rewards.cpp]"]
end

subgraph group_observability["Visualization and records"]
  node_renderer["Live renderer<br/>[renderer.py]"]
  node_monitor["Game monitor<br/>[monitor.py]"]
  node_metrics["Metrics logger<br/>[metrics.py]"]
  node_plotter["Metrics plotter<br/>[plotter.py]"]
  node_checkpointer["Checkpoint manager<br/>[checkpointer.py]"]
  node_reward_viz["Reward visualizer"]
  node_stats_file["Session CSV"]
end

node_operator(("Operator"))

node_operator -->|"starts"| node_main
node_main -->|"reads settings"| node_settings
node_main -->|"creates and steps"| node_environment
node_main -->|"creates and queries"| node_agent
node_main -->|"dispatches training"| node_trainer
node_main -->|"renders"| node_renderer
node_main -->|"updates"| node_monitor
node_main -->|"logs metrics"| node_metrics
node_main -->|"opens plots"| node_plotter
node_main -->|"saves and loads"| node_checkpointer
node_environment -->|"uses death reasons"| node_entities
node_environment -.->|"uses native extension"| node_binding
node_binding -->|"exposes"| node_engine
node_engine -->|"dispatches"| node_physics
node_engine -->|"dispatches"| node_radar
node_engine -->|"dispatches"| node_rewards
node_agent -->|"uses networks"| node_models
node_agent -->|"creates buffer"| node_rollout
node_trainer -->|"updates parameters"| node_agent
node_renderer -->|"draws world"| node_environment
node_renderer -->|"reads statistics"| node_monitor
node_metrics -->|"accepts monitor state"| node_monitor
node_metrics -->|"writes rows"| node_stats_file
node_plotter -->|"reads session data"| node_stats_file
node_plotter -->|"reads team colors"| node_settings

click node_main "https://github.com/muzilyag/snake_ai/blob/main/main.py"
click node_settings "https://github.com/muzilyag/snake_ai/blob/main/src/config.py"
click node_environment "https://github.com/muzilyag/snake_ai/blob/main/src/env/env_wrapper.py"
click node_entities "https://github.com/muzilyag/snake_ai/blob/main/src/env/entity.py"
click node_binding "https://github.com/muzilyag/snake_ai/blob/main/src/engine/pybind_module.cpp"
click node_engine "https://github.com/muzilyag/snake_ai/blob/main/src/engine/vec_env.cpp"
click node_physics "https://github.com/muzilyag/snake_ai/blob/main/src/engine/systems/physics.cpp"
click node_radar "https://github.com/muzilyag/snake_ai/blob/main/src/engine/systems/radar.cpp"
click node_rewards "https://github.com/muzilyag/snake_ai/blob/main/src/engine/systems/rewards.cpp"
click node_agent "https://github.com/muzilyag/snake_ai/blob/main/src/agents/actor.py"
click node_models "https://github.com/muzilyag/snake_ai/blob/main/src/agents/mappo_models.py"
click node_rollout "https://github.com/muzilyag/snake_ai/blob/main/src/agents/rollout.py"
click node_trainer "https://github.com/muzilyag/snake_ai/blob/main/src/agents/mappo_trainer.py"
click node_renderer "https://github.com/muzilyag/snake_ai/blob/main/src/ui/renderer.py"
click node_monitor "https://github.com/muzilyag/snake_ai/blob/main/src/utils/monitor.py"
click node_metrics "https://github.com/muzilyag/snake_ai/blob/main/src/utils/metrics.py"
click node_plotter "https://github.com/muzilyag/snake_ai/blob/main/src/plotter.py"
click node_checkpointer "https://github.com/muzilyag/snake_ai/blob/main/src/utils/checkpointer.py"
click node_reward_viz "https://github.com/muzilyag/snake_ai/blob/main/src/utils/reward_visualizer.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_main,node_settings toneBlue
class node_agent,node_models,node_rollout,node_trainer toneAmber
class node_environment,node_entities,node_binding,node_engine,node_physics,node_radar,node_rewards toneMint
class node_renderer,node_monitor,node_metrics,node_plotter,node_checkpointer,node_reward_viz,node_stats_file toneRose
class node_operator toneIndigo
```

## Components

### Run coordination

- [Training loop](https://github.com/muzilyag/snake_ai/blob/main/main.py): `main.py`
- [Settings](https://github.com/muzilyag/snake_ai/blob/main/src/config.py): `src/config.py`

### MAPPO learning

- [MAPPO agent](https://github.com/muzilyag/snake_ai/blob/main/src/agents/actor.py): `src/agents/actor.py`
- [Actor-critic models](https://github.com/muzilyag/snake_ai/blob/main/src/agents/mappo_models.py): `src/agents/mappo_models.py`
- [Rollout buffer](https://github.com/muzilyag/snake_ai/blob/main/src/agents/rollout.py): `src/agents/rollout.py`
- [MAPPO trainer](https://github.com/muzilyag/snake_ai/blob/main/src/agents/mappo_trainer.py): `src/agents/mappo_trainer.py`

### Game simulation

- [Vector environment](https://github.com/muzilyag/snake_ai/blob/main/src/env/env_wrapper.py): `src/env/env_wrapper.py`
- [Snake entities](https://github.com/muzilyag/snake_ai/blob/main/src/env/entity.py): `src/env/entity.py`
- [Python binding](https://github.com/muzilyag/snake_ai/blob/main/src/engine/pybind_module.cpp): `src/engine/pybind_module.cpp`
- [Vector engine](https://github.com/muzilyag/snake_ai/blob/main/src/engine/vec_env.cpp): `src/engine/vec_env.cpp`
- [Physics system](https://github.com/muzilyag/snake_ai/blob/main/src/engine/systems/physics.cpp): `src/engine/systems/physics.cpp`
- [Radar system](https://github.com/muzilyag/snake_ai/blob/main/src/engine/systems/radar.cpp): `src/engine/systems/radar.cpp`
- [Reward system](https://github.com/muzilyag/snake_ai/blob/main/src/engine/systems/rewards.cpp): `src/engine/systems/rewards.cpp`

### Visualization and records

- [Live renderer](https://github.com/muzilyag/snake_ai/blob/main/src/ui/renderer.py): `src/ui/renderer.py`
- [Game monitor](https://github.com/muzilyag/snake_ai/blob/main/src/utils/monitor.py): `src/utils/monitor.py`
- [Metrics logger](https://github.com/muzilyag/snake_ai/blob/main/src/utils/metrics.py): `src/utils/metrics.py`
- [Metrics plotter](https://github.com/muzilyag/snake_ai/blob/main/src/plotter.py): `src/plotter.py`
- [Checkpoint manager](https://github.com/muzilyag/snake_ai/blob/main/src/utils/checkpointer.py): `src/utils/checkpointer.py`
- [Reward visualizer](https://github.com/muzilyag/snake_ai/blob/main/src/utils/reward_visualizer.py): `src/utils/reward_visualizer.py`
- **Session CSV**

### Other components

- **Operator**

## Connections

- Operator → Training loop: starts
- Training loop → Settings: reads settings (evidence: `main.py`)
- Training loop → Vector environment: creates and steps (evidence: `main.py`)
- Training loop → MAPPO agent: creates and queries (evidence: `main.py`)
- Training loop → MAPPO trainer: dispatches training (evidence: `main.py`)
- Training loop → Live renderer: renders (evidence: `main.py`)
- Training loop → Game monitor: updates (evidence: `main.py`)
- Training loop → Metrics logger: logs metrics (evidence: `main.py`)
- Training loop → Metrics plotter: opens plots (evidence: `main.py`)
- Training loop → Checkpoint manager: saves and loads (evidence: `main.py`)
- Vector environment → Snake entities: uses death reasons (evidence: `src/env/env_wrapper.py`)
- Vector environment → Python binding: uses native extension
- Python binding → Vector engine: exposes (evidence: `src/engine/pybind_module.cpp`)
- Vector engine → Physics system: dispatches (evidence: `src/engine/vec_env.cpp`)
- Vector engine → Radar system: dispatches (evidence: `src/engine/vec_env.cpp`)
- Vector engine → Reward system: dispatches (evidence: `src/engine/vec_env.cpp`)
- MAPPO agent → Actor-critic models: uses networks (evidence: `src/agents/actor.py`)
- MAPPO agent → Rollout buffer: creates buffer (evidence: `src/agents/actor.py`)
- MAPPO trainer → MAPPO agent: updates parameters (evidence: `src/agents/mappo_trainer.py`)
- Live renderer → Vector environment: draws world (evidence: `src/ui/renderer.py`)
- Live renderer → Game monitor: reads statistics (evidence: `src/ui/renderer.py`)
- Metrics logger → Game monitor: accepts monitor state (evidence: `src/utils/metrics.py`)
- Metrics logger → Session CSV: writes rows (evidence: `src/utils/metrics.py`)
- Metrics plotter → Session CSV: reads session data (evidence: `src/plotter.py`)
- Metrics plotter → Settings: reads team colors (evidence: `src/plotter.py`)