# chuyangliu/snake architecture

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

- Interactive diagram: https://gitdiagram.com/chuyangliu/snake
- Repository: https://github.com/chuyangliu/snake

## Overview

##### Main Components
- Game Engine/Core Logic: This is formed by the snake/base folder (files like direc.py, map.py, point.py, pos.py, snake.py) and the game.py file. It represents the internal state and mechanics of the Snake game.
- GUI Module: The snake/gui.py file indicates the graphical user interface, likely based on Python’s Tkinter, that renders the game state and handles user interactions.
- Solver/AI Strategies: The snake/solver directory includes multiple solver implementations:
- DQN Solver: Located under snake/solver/dqn (with history.py, logger.py, memory.py, snakeaction.py)
- Greedy Solver: snake/solver/greedy.py
- Hamilton Solver: snake/solver/hamilton.py
- A possible additional “path” strategy in snake/solver/path.py
- Utility Components: The snake/util folder (with sumtree.py) provides helper functions for probabilistic or algorithmic support, which are especially useful in the DQN implementation.
- Testing/Validation: The tests directory is organized to verify different components (base mechanics, GUI, solver algorithms, and utility functions).
- Tools & Experimentation: The tools folder contains scripts (e.g., plot_dqn_compare.py, plot_dqn_history.py, print_ckpt.py) used for plotting results and debugging, which support the experimentations described in the README.

##### Relationships and Interactions
- run.py acts as the entry point. It likely initializes the game engine, sets up the GUI, and selects a solver strategy based on command-line options or configurations.
- The Game Engine calls the GUI for rendering updates and receives user inputs if any.
- Solver modules interact with the Game Engine by (a) receiving the game state, and (b) outputting moves or decisions to be applied to the game.
- Utility modules (e.g., sumtree) assist solver algorithms for things like memory management or decision weighting.
- The Tools folder scripts are not part of the runtime system but support experimental analysis by extracting data from the game runs or solver outputs.

##### Architectural Patterns & Design Concepts
- Modularity: The clear separation between the game engine, GUI, multiple solver strategies, and utilities is an example of modular design. Each module focuses on one aspect of the problem.
- Strategy Pattern: The different solver implementations suggest a strategy pattern where the game engine can interchangeably use a DQN, greedy, or Hamilton algorithm.
- Testing & Experimentation: A comprehensive test suite indicates a design that supports continuous validation and iterative improvement.
- MVC-Like Separation: Although not strictly Model-View-Controller, there is a separation between the “model” (game state and logic) and “view” (GUI), with solver modules acting as controllers or decision engines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Components
    subgraph "Runtime Components"
        entry("run.py (Entry Point)"):::runtime
        engine("Game Engine / Core Logic:\nsnake/base/ & snake/game.py"):::runtime
        gui("GUI Module:\nsnake/gui.py"):::runtime
        subgraph "Solver Module"
            dqn("DQN Solver:\nsnake/solver/dqn/"):::runtime
            greedy("Greedy Solver:\nsnake/solver/greedy.py"):::runtime
            hamilton("Hamilton Solver:\nsnake/solver/hamilton.py"):::runtime
            path("Path Solver:\nsnake/solver/path.py"):::runtime
        end
    end

    %% Support Components
    subgraph "Support Components"
        util("Utilities:\nsnake/util/sumtree.py"):::support
        tools("Tools & Experimentation:\ntools/"):::tool
        tests("Testing & Validation:\ntests/"):::support
    end

    %% Connections
    entry -->|"initialize"| engine
    entry -->|"initialize"| gui
    entry -->|"select_solver"| dqn
    entry -->|"select_solver"| greedy
    entry -->|"select_solver"| hamilton
    entry -->|"select_solver"| path

    engine -->|"state_update"| gui
    engine -->|"provides_state"| dqn
    engine -->|"provides_state"| greedy
    engine -->|"provides_state"| hamilton
    engine -->|"provides_state"| path

    dqn -->|"move_command"| engine
    greedy -->|"move_command"| engine
    hamilton -->|"move_command"| engine
    path -->|"move_command"| engine

    util -->|"support_functions"| dqn
    util -->|"support_functions"| greedy
    util -->|"support_functions"| hamilton
    util -->|"support_functions"| path

    tools -.->|"analysis"| engine
    tools -.->|"analysis"| dqn
    tools -.->|"analysis"| greedy
    tools -.->|"analysis"| hamilton
    tools -.->|"analysis"| path

    tests -->|"validates"| engine
    tests -->|"validates"| gui
    tests -->|"validates"| dqn
    tests -->|"validates"| greedy
    tests -->|"validates"| hamilton
    tests -->|"validates"| path
    tests -->|"validates"| util

    %% Click Events
    click entry "https://github.com/chuyangliu/snake/blob/main/run.py"
    click engine "https://github.com/chuyangliu/snake/tree/main/snake/base/"
    click gui "https://github.com/chuyangliu/snake/blob/main/snake/gui.py"
    click dqn "https://github.com/chuyangliu/snake/tree/main/snake/solver/dqn/"
    click greedy "https://github.com/chuyangliu/snake/blob/main/snake/solver/greedy.py"
    click hamilton "https://github.com/chuyangliu/snake/blob/main/snake/solver/hamilton.py"
    click path "https://github.com/chuyangliu/snake/blob/main/snake/solver/path.py"
    click util "https://github.com/chuyangliu/snake/blob/main/snake/util/sumtree.py"
    click tools "https://github.com/chuyangliu/snake/tree/main/tools/"
    click tests "https://github.com/chuyangliu/snake/tree/main/tests/"

    %% Styling Definitions
    classDef runtime fill:#ffcccc,stroke:#b30000,stroke-width:2px;
    classDef support fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef tool fill:#cce5ff,stroke:#003366,stroke-width:2px;
```
