# a-kalleri/snake architecture

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

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

## Overview

##### Project type & purpose (from README + tree)
This is a **single-binary desktop game**: a classic **Snake** implemented in **C** on **Windows** using the **Win32 API**.
The entire implementation appears to live in **one source file** (`snake.c`), so the “architecture” is primarily **runtime components** and **logical modules inside the file**, not multiple deployable services.

- It’s a **Win32 event-driven application** (message loop + window procedure).
- Game behavior is controlled by **input events** (WASD, Space) and a **tick/update loop** (timer or similar).
- Rendering uses Win32 drawing (likely GDI) into a window client area.
- Optional behaviors are toggled via **command-line flags** (`--warp`, speed levels, `--mute`).
- Sound uses simple Win32 beeps (or equivalent).

##### OS / Platform layer (external dependencies)
- **Windows OS**
- **Win32 API**
- `User32` (window creation, message loop, keyboard input)
- `GDI32` (rendering primitives, painting)
- `Kernel32` (timers, process args, misc)
- (Optional) Sound APIs (often `Beep()`)

##### Startup / Configuration
- Command-line parsing:
- `--warp` (wrapping mode)
- `--lv2`, `--lv3`, `--frenzy` (speed)
- `--mute` (sound off)
- Initializes game settings and creates the window.

##### Window + Eventing
- **WinMain** (or equivalent) sets up window class, creates window.
- **Message loop**: dispatches events to window procedure.
- **Window procedure (WndProc)**: handles:
- `WM_KEYDOWN` (WASD, Space)
- `WM_TIMER` (game tick) or another mechanism that triggers periodic updates
- `WM_DESTROY` / quit

##### Game Loop (Tick-based)
- On each tick:
- Move snake
- Detect collisions:
- walls (game over vs wrap)
- self-collision (game over)
- apple consumption (grow, increase score)
- Trigger re-render (invalidate/paint)

##### Game State
- Snake body representation (list/array of segments)
- Direction + “direction change” rules
- Apple position (random placement)
- Score
- Game Over flag / Restart logic
- Speed/tick interval (based on lv2/lv3/frenzy)

##### Rendering
- Update score display in **window title** (per README)
- Likely uses `WM_PAINT` + GDI calls, or draws into a backbuffer then blits.

##### Audio
- Direction change beep
- Apple consumption beep
- Muting toggles the audio calls off

##### Primary runtime flow (high-level)
**Windows OS** → (delivers messages) → **Message Loop** → (dispatch) → **WndProc** → (calls) → **Game Logic / State Update** → (requests) → **Rendering** → (draws via) → **GDI / Window**

##### Input flow
**Keyboard (WASD/Space)** → `WM_KEYDOWN` → **Input Handler** → updates **Direction / Restart** → affects next **Tick Update**

##### Tick/update flow
**Timer / Tick Source** → `WM_TIMER` (or equivalent) → **Update Step** → modifies **Game State** → triggers **Invalidate/Redraw**

##### Score/UI flow
**Game State (score)** → **UI Update** (SetWindowText / title update) → **Window Title**

##### Audio flow
**Game Events** (turn, eat apple) → **Sound Module** → **Beep()** (unless muted)

##### Configuration flow
**Command line args** → **Config** → influences:
- Tick interval (speed)
- Wall behavior (warp)
- Sound enabled/disabled

Purpose: show what the program is and its external dependencies.

Purpose: show the internal logical modules and how events cause updates/renders.
- Startup/Args Parser
- Message Loop
- WndProc (Event Router)
- Input Handler
- Tick/Update Engine
- Game State
- Collision/Rules (including Warp Mode)
- Apple/Random Placement
- Renderer (GDI)
- UI/Title Updater (score)
- Audio (mute-able)
- `WM_KEYDOWN`, `WM_TIMER`, `WM_PAINT` routes
- Update → State → Render
- State → Title update
- Events → Audio

##### Important architectural patterns to highlight (what’s “essential” here)
- **Event-driven architecture** (Win32 message pump).
- **Tick-based game loop** integrated into Win32 via **timer messages** or periodic invalidation.
- **Separation of concerns (logical)** even if physically one file:
- Input vs Update vs Render vs State.
- **Feature flags/config** at startup (warp/speed/mute).

##### What to label explicitly (tech + behavior)
- “WM_KEYDOWN (W/A/S/D, Space)”
- “WM_TIMER (tick interval = speed level)”
- “InvalidateRect/Redraw” (if that’s how paint is triggered)
Also label configuration influences:
- “--warp: edge collision => wrap vs game over”
- “--mute: suppress beep”
- “--lv2/--lv3/--frenzy: tick interval”

- Prefer “Tick/Update Engine” over “Logic”.
- Prefer “Renderer (GDI via WM_PAINT)” over “Graphics”.
- OS → MessageLoop → WndProc → Update/Render
- External/system (Windows, Win32 DLLs): grey
- Eventing (Message loop/WndProc): blue
- Game core (State/Update/Rules): green
- I/O (Keyboard, Sound): orange
- Rendering/UI: purple

##### “Don’t overthink it” but still be very detailed: how to decompose aggressively

A good final layout is:
- Left: **Windows OS + inputs** feeding the message loop.
- Center: **WndProc** as the event router.
- Right: two lanes:
- **Update lane** (tick → rules/collisions → state)

That will produce the most accurate representation of a Win32 C snake game without pretending it’s a multi-service system.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: Context / Container
  %% =========================
  subgraph "Diagram 1 — Context / Container (snake.exe)"
    direction TB

    OS["Windows OS"]:::external
    subgraph "Win32 API (DLLs)"
      direction TB
      User32["User32 (window,msg,input)"]:::external
      GDI32["GDI32 (WM_PAINT drawing)"]:::external
      Kernel32["Kernel32 (timers,args,misc)"]:::external
    end

    KB["Keyboard (W/A/S/D,Space)"]:::io
    TMR["Timer / Tick Source"]:::io
    SND["Sound API (Beep)"]:::io

    APPCTX["Snake Game (snake.exe)"]:::app

    OS -.->|"delivers_messages"| APPCTX
    KB -.->|"WM_KEYDOWN"| APPCTX
    TMR -.->|"WM_TIMER"| APPCTX

    APPCTX -->|"calls"| User32
    APPCTX -->|"draws_via"| GDI32
    APPCTX -->|"uses"| Kernel32
    APPCTX -->|"optional_calls"| SND
  end

  %% =========================
  %% Diagram 2: Component / Runtime flow (inside snake.c)
  %% =========================
  subgraph "Diagram 2 — Component / Runtime Flow (logical modules inside snake.c)"
    direction TB

    subgraph "Platform Eventing (Win32)"
      direction TB
      WinMainCfg["Startup / Configuration (WinMain + args)"]:::event
      MsgLoop["Message Loop (GetMessage/DispatchMessage)"]:::event
      WndProc["WndProc (Event Router)"]:::event
    end

    subgraph "Input Lane"
      direction TB
      InputH["Input Handler (W/A/S/D + Space)"]:::io
      DirRules["Direction Rules (no_reverse,etc.)"]:::core
      Restart["Restart / Reset (Space)"]:::core
    end

    subgraph "Update Lane (Tick-based)"
      direction TB
      Tick["Tick / Update Engine (WM_TIMER)"]:::core
      Rules["Collision / Rules (--warp,self,apple)"]:::core
      Apple["Apple / Random Placement (spawn)"]:::core
      State["Game State (snake,dir,apple,score,flags,speed)"]:::core
    end

    subgraph "Render Lane (WM_PAINT)"
      direction TB
      Invalidate["Invalidate / Redraw Request"]:::render
      Renderer["Rendering (GDI via WM_PAINT)"]:::render
      Title["UI / Title Updater (score in title)"]:::render
    end

    subgraph "Audio Lane"
      direction TB
      Audio["Audio (beep; gated by --mute)"]:::io
    end

    %% --- Startup / config flow
    WinMainCfg -->|"creates_window_class+window"| MsgLoop
    WinMainCfg -->|"config:--warp/--mute/--lv2/--lv3/--frenzy"| State
    WinMainCfg -->|"sets_tick_interval"| Tick

    %% --- Message/event dispatch
    OS2["Windows OS"]:::external
    OS2 -.->|"messages"| MsgLoop
    MsgLoop -->|"DispatchMessage"| WndProc

    %% --- WndProc routes
    WndProc -.->|"WM_KEYDOWN (W/A/S/D,Space)"| InputH
    WndProc -.->|"WM_TIMER (tick_interval=speed)"| Tick
    WndProc -.->|"WM_PAINT (GDI draw)"| Renderer
    WndProc -.->|"WM_DESTROY / Quit"| MsgLoop

    %% --- Input handling effects
    InputH -->|"turn_request"| DirRules
    DirRules -->|"update_direction"| State
    InputH -->|"Space"| Restart
    Restart -->|"reset_state"| State

    %% --- Tick/update loop
    Tick -->|"step_move+update"| Rules
    Rules -->|"wrap_or_gameover (--warp)"| State
    Rules -->|"self_collision=>game_over"| State
    Rules -->|"apple_eaten=>grow+score"| State
    Rules -->|"needs_new_apple"| Apple
    Apple -->|"place_apple_randomly"| State
    Tick -->|"trigger_repaint"| Invalidate
    Invalidate -->|"causes_WM_PAINT"| WndProc

    %% --- Render flow uses state
    State -->|"read_state"| Renderer
    Renderer -->|"GDI_draw_snake+apple+board"| GDI32

    %% --- Score/title
    State -->|"score_changed"| Title
    Title -->|"SetWindowText (window_title)"| User32

    %% --- Audio events (gated by mute flag)
    DirRules -->|"turn_event"| Audio
    Rules -->|"apple_eaten_event"| Audio
    Audio -->|"Beep() unless --mute"| SND

    %% --- External dll references (contextual)
    WndProc -->|"uses"| User32
    Tick -->|"timer_mgmt"| Kernel32
    WinMainCfg -->|"args_parsing"| Kernel32
  end

  %% =========================
  %% Legend
  %% =========================
  subgraph "Legend"
    direction TB
    L1["External/System"]:::external
    L2["Eventing (Message pump/WndProc)"]:::event
    L3["Game Core (State/Update/Rules)"]:::core
    L4["I/O (Keyboard/Audio/Timer)"]:::io
    L5["Rendering/UI"]:::render
    LA["Solid arrow = call/data flow"]:::legend
    LB["Dashed arrow = OS message/event"]:::legend
  end

  %% =========================
  %% Click Events (component mapping -> snake.c)
  %% =========================
  click APPCTX "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click WinMainCfg "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click MsgLoop "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click WndProc "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click Tick "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click State "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click Rules "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click Apple "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click Renderer "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click Title "https://github.com/a-kalleri/snake/blob/main/snake.c"
  click Audio "https://github.com/a-kalleri/snake/blob/main/snake.c"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#E5E7EB,stroke:#6B7280,stroke-width:1px,color:#111827
  classDef event fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#0B1B3A
  classDef core fill:#DCFCE7,stroke:#16A34A,stroke-width:1px,color:#05210F
  classDef io fill:#FFEDD5,stroke:#F97316,stroke-width:1px,color:#2A1203
  classDef render fill:#F3E8FF,stroke:#7C3AED,stroke-width:1px,color:#1F1147
  classDef app fill:#FFFFFF,stroke:#111827,stroke-width:2px,color:#111827
  classDef legend fill:#FFFFFF,stroke:#9CA3AF,stroke-width:1px,color:#111827
```
