# kelwynoliveira/pysnake architecture

> Architecture diagram of the GitHub repository kelwynoliveira/pysnake, 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/kelwynoliveira/pysnake
- Repository: https://github.com/kelwynoliveira/pysnake

## Overview

PySnake is a single-file terminal Snake game. The user selects a speed, then steers the snake while the game loop updates its position, checks fruit and collisions, tracks score, and displays the result. The diagram separates control, game rules, and terminal presentation while keeping the actual function-call ownership visible. All runtime code is in `pysnake.py`; the README documents the gameplay and difficulty levels, and the supplied source shows their implementation.

Main entry points: [`pysnake.py`](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py) (Game loop)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Game control"]
  node_entry["Program entry<br/>[pysnake.py]"]
  node_difficulty["Difficulty selection<br/>[pysnake.py]"]
  node_loop["Game loop<br/>[pysnake.py]"]
  node_finish["End-game screen<br/>[pysnake.py]"]
end

subgraph group_rules["Game rules"]
  node_movement["Move snake<br/>[pysnake.py]"]
  node_actor_move["Move actor<br/>[pysnake.py]"]
  node_direction_rule["Reject reversal<br/>[pysnake.py]"]
  node_fruit_rule["Check fruit<br/>[pysnake.py]"]
  node_fruit_spawn["Spawn fruit<br/>[pysnake.py]"]
  node_self_collision["Self collision<br/>[pysnake.py]"]
  node_border_collision["Border collision<br/>[pysnake.py]"]
  node_actor_border["Check border<br/>[pysnake.py]"]
end

subgraph group_terminal["Terminal interface"]
  node_direction["Read direction<br/>[pysnake.py]"]
  node_screen["Draw screen<br/>[pysnake.py]"]
  node_snake_draw["Draw snake<br/>[pysnake.py]"]
  node_actor_draw["Draw actor<br/>[pysnake.py]"]
end

node_player(("Player"))
node_random["Python random"]
node_terminal_io["Terminal"]

node_player -->|"chooses speed"| node_difficulty
node_entry -->|"selects speed"| node_difficulty
node_entry -->|"launches game"| node_loop
node_player -->|"presses keys"| node_direction
node_loop -->|"reads input"| node_direction
node_loop -->|"draws frame"| node_screen
node_loop -->|"draws snake"| node_snake_draw
node_loop -->|"draws fruit"| node_actor_draw
node_loop -->|"checks reversal"| node_direction_rule
node_loop -->|"moves snake"| node_movement
node_movement -->|"moves head"| node_actor_move
node_loop -->|"checks border"| node_border_collision
node_border_collision -->|"checks head"| node_actor_border
node_loop -->|"checks self-hit"| node_self_collision
node_loop -->|"checks fruit"| node_fruit_rule
node_loop -->|"spawns fruit"| node_fruit_spawn
node_fruit_spawn -->|"chooses position"| node_random
node_loop -->|"shows score"| node_finish
node_screen -->|"draws frame"| node_terminal_io
node_snake_draw -->|"draws segments"| node_actor_draw
node_actor_draw -->|"writes characters"| node_terminal_io
node_direction -->|"reads keys"| node_terminal_io
node_finish -->|"shows result"| node_terminal_io

click node_entry "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_difficulty "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_loop "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_finish "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_direction "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_screen "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_snake_draw "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_actor_draw "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_movement "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_actor_move "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_direction_rule "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_fruit_rule "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_fruit_spawn "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_self_collision "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_border_collision "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py"
click node_actor_border "https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.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_difficulty,node_loop,node_finish toneBlue
class node_movement,node_actor_move,node_direction_rule,node_fruit_rule,node_fruit_spawn,node_self_collision,node_border_collision,node_actor_border toneAmber
class node_direction,node_screen,node_snake_draw,node_actor_draw toneMint
class node_player,node_random,node_terminal_io toneIndigo
```

## Components

### Game control

- [Program entry](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Difficulty selection](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Game loop](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [End-game screen](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`

### Game rules

- [Move snake](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Move actor](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Reject reversal](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Check fruit](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Spawn fruit](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Self collision](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Border collision](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Check border](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`

### Terminal interface

- [Read direction](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Draw screen](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Draw snake](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`
- [Draw actor](https://github.com/kelwynoliveira/pysnake/blob/main/pysnake.py): `pysnake.py`

### Other components

- **Player**
- **Python random**
- **Terminal**

## Connections

- Player → Difficulty selection: chooses speed
- Program entry → Difficulty selection: selects speed
- Program entry → Game loop: launches game
- Player → Read direction: presses keys
- Game loop → Read direction: reads input
- Game loop → Draw screen: draws frame
- Game loop → Draw snake: draws snake
- Game loop → Draw actor: draws fruit
- Game loop → Reject reversal: checks reversal
- Game loop → Move snake: moves snake
- Move snake → Move actor: moves head
- Game loop → Border collision: checks border
- Border collision → Check border: checks head
- Game loop → Self collision: checks self-hit
- Game loop → Check fruit: checks fruit
- Game loop → Spawn fruit: spawns fruit
- Spawn fruit → Python random: chooses position
- Game loop → End-game screen: shows score
- Draw screen → Terminal: draws frame
- Draw snake → Draw actor: draws segments
- Draw actor → Terminal: writes characters
- Read direction → Terminal: reads keys
- End-game screen → Terminal: shows result