# code-bullet/snakefusion architecture

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

- Interactive diagram: https://gitdiagram.com/code-bullet/snakefusion
- Repository: https://github.com/code-bullet/snakefusion

## Overview

##### Project Type and Purpose
- The project is a simulation/game built in Processing that uses genetic algorithms and neural networks to train several “snake” agents. These agents then fuse into a “super snake” – hence the project name “SnakeFusion.”
- The README explains that the project evolves snakes (using genetic algorithms) and fuses them into a superior snake. User inputs (e.g., adjusting the mutation rate, displaying best snakes, fusing snakes) further hint at interactive simulation behavior.

##### File Structure
- Top-Level Files:
- README.md provides an overview of the project purpose and instructions.
- Directory “SmartSnakesCombine” contains most of the source code in multiple .pde files, which is typical for Processing projects.
- The individual source files (Food.pde, Matrix.pde, NeuralNet.pde, Population.pde, Snake.pde, SuperSnake.pde, SuperSnakeClone.pde, World.pde) clearly hint at dedicated modules:
○ Food.pde – likely handles food placement/logic for the snake’s environment.
○ Matrix.pde – might be used for managing data representations or neural network matrices.
○ NeuralNet.pde – contains implementations for the neural network of each snake.
○ Population.pde – oversees the evolution/genetic algorithm aspects, managing multiple snake agents.
○ Snake.pde – defines the base snake behavior/attributes.
○ SuperSnake.pde and SuperSnakeClone.pde – responsible for the “fusion” of selected snakes into an advanced snake version.
○ World.pde – likely manages the overall simulation environment.
- The “data” folder contains a CSV file (snakesStored.csv) which probably stores saved snake genomes or states for further training.

##### Key Components and Their Interactions
- Simulation Environment (World.pde):
- Acts as the main loop and container for the simulation.
- Manages interaction between game entities.
- Snake Entities:
- Snake.pde covers regular snake behavior.
- SuperSnake and SuperSnakeClone handle advanced/combined snake versions.
- Genetic Algorithm and Neural Network:
- Population.pde governs the evolution cycle of snakes (selection, mutation, reproduction).
- NeuralNet.pde implements the decision-making logic of each snake.
- Matrix.pde may support data manipulation for neural network operations.
- Environment Objects:
- Food.pde handles food logic, influencing snake behavior and evolution.
- Persistence/Storage:
- Stored data (snakesStored.csv in the data directory) is used to save and load snake configurations, supporting further training and replay.

a. Main Components:
- Simulation/Environment Component: Represented by World.pde.
- Snake Agents: Include components from Snake.pde, SuperSnake.pde, and SuperSnakeClone.pde.
- Genetic Evolution Module: Captured by Population.pde and NeuralNet.pde with support from Matrix.pde.
- Environmental Elements: Food.pde representing food objects.
- Data Persistence: Data storage module (snakesStored.csv) in the “data” directory.
- User Interaction: Capture keyboard controls (e.g., space, d, h, 0–4, L, f) influencing simulation behavior.

b. Relationships and Interactions:
- World (simulation engine) orchestrates the entire system:
- It initializes and updates Snake agents.
- It invokes Population methods to handle genetic evolution.
- It manages Food placement which interacts with Snake’s behavior.
- Snake agents use their individual NeuralNet configurations to make decisions.
- The Population module processes performance data from snakes (fitness values) and triggers mutations or crossovers.
- User input dynamically alters parameters (mutation rate, snake display) and can trigger specialized functions like snake fusion.
- Data persistence allows for saving chosen snake genomes, which can later be reintroduced or fused.

c. Architectural Patterns and Design Principles:
- Modular Design: Each .pde file represents a clear module or object.
- Separation of Concerns: Simulation, genetic algorithm, and display/input logic are kept largely distinct.
- Data Flow – the simulation loop (via World.pde) orchestrates interactions where snake decisions (driven by neural networks) are fed into the evolving population module. User inputs further alter parameters, influencing the evolution process.
- Use of External Storage: The CSV is used to store critical state information, highlighting persistence in design.

d. Relevant Technologies and Libraries:
- Processing framework: Basis for the simulation and rendering.
- Genetic Algorithm & Neural Network techniques integrated into the code, likely custom-implemented without heavy external libraries.
- CSV data handling for persisting snake states.

## Diagram (Mermaid)

```mermaid
flowchart TD
    App["Main Application"]:::simulation
    World["World / Simulation Engine"]:::simulation
    Population["Population / Genetic Algorithm Manager"]:::genetic
    Neural["Neural Network (Decision Making)"]:::genetic
    Matrix["Matrix (Data Manipulation)"]:::genetic
    Snake["Snake Entity"]:::agent
    SuperSnake["SuperSnake (Fused Snake)"]:::agent
    SuperSnakeClone["SuperSnakeClone (Fused Snake Functionality)"]:::agent
    Food["Food / Environment Elements"]:::env
    DataStorage["Data Persistence (Snake Genome Storage)"]:::env
    UserInput["User Input (Keyboard Controls)"]:::user

    App -->|"starts"| World
    World -->|"initializes"| Snake
    World -->|"initializes"| SuperSnake
    World -->|"initializes"| SuperSnakeClone
    World -->|"manages"| Food
    World -->|"orchestrates"| Population
    Population -->|"triggers"| Neural
    Population -->|"supports"| Matrix
    Neural -->|"influences"| Snake
    Matrix -->|"supports"| Neural
    Population -->|"saves_to"| DataStorage
    UserInput -->|"modifies"| World
    UserInput -->|"modifies"| Population

    click App "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/SmartSnakesCombine.pde"
    click World "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/World.pde"
    click Snake "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/Snake.pde"
    click SuperSnake "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/SuperSnake.pde"
    click SuperSnakeClone "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/SuperSnakeClone.pde"
    click Food "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/Food.pde"
    click Population "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/Population.pde"
    click Neural "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/NeuralNet.pde"
    click Matrix "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/Matrix.pde"
    click DataStorage "https://github.com/code-bullet/snakefusion/blob/master/SmartSnakesCombine/data/snakesStored.csv"

    classDef simulation fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef genetic fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef agent fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef env fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef user fill:#FFA07A,stroke:#000,stroke-width:2px;
```
