# abhhiinv/snakegame architecture

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

- Interactive diagram: https://gitdiagram.com/abhhiinv/snakegame
- Repository: https://github.com/abhhiinv/snakegame

## Overview

1. **Overall shape**
   - This is a small, single-process **Java Swing** desktop game.
   - The repository is organized around three Java classes plus image assets: a game entry point, a playable board, and a menu panel.

2. **Entry point and application bootstrap**
   - `SnakeGame.java` is the application launcher.
   - It is responsible for starting the Swing UI and wiring the initial screen flow, likely switching between the menu and the active game board.

3. **Main gameplay surface**
   - `Board.java` is the core game subsystem.
   - It likely owns the snake state, apple spawning, movement updates, collision detection, score tracking, special-apple timing, and game-over handling.
   - In architecture terms, this is the central stateful component where most game logic lives.

4. **Menu / difficulty selection**
   - `MenuPanel.java` is the pre-game UI.
   - Its role is to let the player choose difficulty before starting a session.
   - This is a separate UI boundary from the gameplay board, which helps keep setup concerns away from the real-time game loop.

5. **Game loop and real-time updates**
   - The board is a real-time interactive component rather than a request/response app.
   - Updates are driven by Swing’s event/timer mechanisms and keyboard input, with continuous redraws as the snake moves.
   - The architecture is thus event-driven: input events, timer ticks, and collision outcomes drive state transitions.

6. **Input and control flow**
   - Arrow keys are the primary input channel.
   - The game validates direction changes to prevent illegal 180° reversals.
   - Input changes feed directly into the board’s movement state, which then affects the next update tick.

7. **Gameplay state and scoring**
   - The board maintains score and progression state across the session.
   - Normal apples award 1 point and increase snake length.
   - A special apple introduces a second scoring path: it appears every 5 normal apples, is worth 5 points, and is time-limited.

8. **Timed special-event subsystem**
   - The special apple behaves like a small timed subsystem inside the game board.
   - The UI includes a countdown/progress bar at the bottom to show remaining time.
   - This creates an additional game-state branch beyond standard movement and collision logic.

9. **Persistence boundary**
   - High scores are written to and read from `highscores.txt`.
   - That file is the only explicit persistent storage in the repo, and it stores the top 5 scores together with the selected difficulty.
   - This separates short-lived in-memory gameplay state from durable leaderboard state.

10. **Visual layer and assets**
   - The `icons/` directory contains custom PNG sprites for the snake and apples.
   - Rendering is handled in Swing with retro-style 2D graphics rather than a scene graph or game engine.
   - The visuals are part of the client UI layer; there is no backend rendering service.

11. **Game over and results presentation**
   - When the snake collides with walls or itself, the board transitions into a game-over state.
   - That state includes score display, leaderboard presentation, and new-high-score feedback.
   - This is likely a distinct UI mode within the same Swing window rather than a separate screen process.

12. **Project boundary and deployment model**
   - The project is self-contained and runs from the command line with `javac`/`java`.
   - There are no external services, databases, or network dependencies.
   - For an architecture diagram, the key boundary is simply: **desktop Swing UI + in-memory game state + file-based high-score persistence**.

Main entry points: [`Board.java`](https://github.com/abhhiinv/snakegame/blob/main/Board.java) (Board), [`MenuPanel.java`](https://github.com/abhhiinv/snakegame/blob/main/MenuPanel.java) (Menu Panel), [`SnakeGame.java`](https://github.com/abhhiinv/snakegame/blob/main/SnakeGame.java) (SnakeGame), [`icons`](https://github.com/abhhiinv/snakegame/tree/main/icons) (Icons)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Swing UI"]
  node_snakegame["SnakeGame<br/>launcher<br/>[SnakeGame.java]"]
  node_menu["Menu Panel<br/>selection ui<br/>[MenuPanel.java]"]
end

subgraph group_game["Gameplay Core"]
  node_board["Board<br/>[Board.java]"]
  node_input(("Keyboard Input<br/>control input"))
  node_loop(("Game Loop<br/>timer loop"))
  node_movement{{"Snake State<br/>runtime state"}}
  node_apples{{"Apple Logic<br/>spawn/scoring"}}
  node_special{{"Special Apple<br/>timed bonus"}}
  node_results["Game Over<br/>results ui"]
end

subgraph group_data["Persistence & Assets"]
  node_scores[("High Scores<br/>file persistence")]
  node_assets["Icons<br/>sprite assets"]
end

node_snakegame -->|"show menu"| node_menu
node_snakegame -->|"start game"| node_board
node_menu -->|"launch with difficulty"| node_board
node_board -->|"read keys"| node_input
node_input -->|"update direction"| node_movement
node_board -->|"run updates"| node_loop
node_loop -->|"advance snake"| node_movement
node_loop -->|"check eat"| node_apples
node_apples -->|"promote bonus"| node_special
node_special -->|"countdown"| node_board
node_board -->|"collision ends game"| node_results
node_results -->|"save score"| node_scores
node_scores -->|"restore leaderboard"| node_menu
node_board -->|"render sprites"| node_assets
node_menu -->|"decorate ui"| node_assets

click node_snakegame "https://github.com/abhhiinv/snakegame/blob/main/SnakeGame.java"
click node_menu "https://github.com/abhhiinv/snakegame/blob/main/MenuPanel.java"
click node_board "https://github.com/abhhiinv/snakegame/blob/main/Board.java"
click node_assets "https://github.com/abhhiinv/snakegame/tree/main/icons"

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_snakegame,node_menu toneBlue
class node_board,node_input,node_loop,node_movement,node_apples,node_special,node_results toneAmber
class node_scores,node_assets toneMint
```

## Components

### Swing UI

Application launch, menu, and game window surfaces.

- [SnakeGame](https://github.com/abhhiinv/snakegame/blob/main/SnakeGame.java): launcher · Application entry point and Swing bootstrap. · `SnakeGame.java`
- [Menu Panel](https://github.com/abhhiinv/snakegame/blob/main/MenuPanel.java): selection ui · Pre-game screen for choosing difficulty and starting a session. · `MenuPanel.java`

### Gameplay Core

Real-time snake state, input, scoring, and game-over flow.

- [Board](https://github.com/abhhiinv/snakegame/blob/main/Board.java): game board · Main interactive play surface and central game state holder. · `Board.java`
- **Keyboard Input**: control input · Arrow-key direction changes that feed the snake movement state.
- **Game Loop**: timer loop · Swing-driven update and repaint cycle for real-time play.
- **Snake State**: runtime state · Snake body, direction, and legal movement transitions.
- **Apple Logic**: spawn/scoring · Normal apple spawning, consumption, and score growth.
- **Special Apple**: timed bonus · Time-limited bonus apple that appears periodically and scores extra points.
- **Game Over**: results ui · Collision outcome, score summary, and new-high-score feedback.

### Persistence & Assets

File-backed leaderboard storage and sprite assets.

- **High Scores**: file persistence · Top-five leaderboard stored with difficulty in highscores.txt.
- [Icons](https://github.com/abhhiinv/snakegame/tree/main/icons): sprite assets · PNG sprites used for snake and apple rendering. · `icons`

## Connections

- SnakeGame → Menu Panel: show menu · Launches the initial difficulty selection screen.
- SnakeGame → Board: start game · Creates the playable board for a new session.
- Menu Panel → Board: launch with difficulty · Passes the selected difficulty into gameplay setup.
- Board → Keyboard Input: read keys · Consumes arrow-key events for movement control.
- Keyboard Input → Snake State: update direction · Changes heading while preventing illegal reversals.
- Board → Game Loop: run updates · Uses Swing timing to advance the game and repaint.
- Game Loop → Snake State: advance snake · Moves the snake on each tick.
- Game Loop → Apple Logic: check eat · Detects apple collisions and grows the snake.
- Apple Logic → Special Apple: promote bonus · Every five normal apples, a special timed apple can appear.
- Special Apple → Board: countdown · Maintains time-limited bonus state inside the board.
- Board → Game Over: collision ends game · Transitions to game-over mode on wall or self collision.
- Game Over → High Scores: save score · Writes leaderboard updates to the score file.
- High Scores → Menu Panel: restore leaderboard · Loads persisted high scores for display and comparison.
- Board → Icons: render sprites · Draws snake and apple graphics from the icon set.
- Menu Panel → Icons: decorate ui · Uses shared image assets for the front screen.
