# naskarepo/demos architecture

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

- Interactive diagram: https://gitdiagram.com/naskarepo/demos
- Repository: https://github.com/naskarepo/demos

## Overview

This repository is a set of three Windows-oriented terminal animation demos: granular materials, flocking boids, and a vortex. Each demo initializes its own simulation, updates it in a loop, and renders frames; the sand demo additionally accepts keys to move a spawner and create materials. Shared utilities handle keyboard input, 2D maps, and incremental frame rendering. The README and sampled files establish these flows; the demos otherwise operate independently.

Main entry points: [`utils/keyboard.py`](https://github.com/naskarepo/demos/blob/main/utils/keyboard.py) (Keyboard thread), [`utils/frameBuffer.py`](https://github.com/naskarepo/demos/blob/main/utils/frameBuffer.py) (Frame buffer), [`utils/map2d.py`](https://github.com/naskarepo/demos/blob/main/utils/map2d.py) (2D map helpers), [`sand.py`](https://github.com/naskarepo/demos/blob/main/sand.py) (Sand simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demos["Simulation demos"]
  node_sand["Sand simulation<br/>[sand.py]"]
  node_flocking["Flocking simulation<br/>[flocking.py]"]
  node_vortex["Vortex simulation<br/>[vortex.py]"]
end

subgraph group_utilities["Shared utilities"]
  node_keyboard["Keyboard thread<br/>[keyboard.py]"]
  node_getkey["Key decoder<br/>[getKey.py]"]
  node_map["2D map helpers<br/>[map2d.py]"]
  node_framebuffer["Frame buffer<br/>[frameBuffer.py]"]
end

subgraph group_platform["Terminal and input"]
  node_windows["Windows key input"]
  node_terminal(("Terminal display"))
end

node_user(("Keyboard user"))

node_user -->|"presses keys"| node_windows
node_windows -->|"provides key bytes"| node_getkey
node_sand -->|"starts input thread"| node_keyboard
node_flocking -->|"starts input thread"| node_keyboard
node_vortex -->|"starts input thread"| node_keyboard
node_keyboard -->|"reads keys"| node_getkey
node_keyboard -->|"dispatches callback"| node_sand
node_keyboard -->|"dispatches callback"| node_flocking
node_keyboard -->|"dispatches callback"| node_vortex
node_sand -->|"creates and swaps"| node_map
node_flocking -->|"creates map"| node_map
node_vortex -->|"creates map"| node_map
node_sand -->|"draws frames"| node_framebuffer
node_flocking -->|"draws frames"| node_framebuffer
node_vortex -->|"draws frames"| node_framebuffer
node_framebuffer -->|"prints initial map"| node_map
node_map -->|"prints map"| node_terminal
node_framebuffer -->|"prints changed cells"| node_terminal

click node_sand "https://github.com/naskarepo/demos/blob/main/sand.py"
click node_flocking "https://github.com/naskarepo/demos/blob/main/flocking.py"
click node_vortex "https://github.com/naskarepo/demos/blob/main/vortex.py"
click node_keyboard "https://github.com/naskarepo/demos/blob/main/utils/keyboard.py"
click node_getkey "https://github.com/naskarepo/demos/blob/main/utils/getKey.py"
click node_map "https://github.com/naskarepo/demos/blob/main/utils/map2d.py"
click node_framebuffer "https://github.com/naskarepo/demos/blob/main/utils/frameBuffer.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_sand,node_flocking,node_vortex,node_user toneBlue
class node_keyboard,node_getkey,node_map,node_framebuffer toneAmber
class node_windows,node_terminal toneMint
```

## Components

### Simulation demos

- [Sand simulation](https://github.com/naskarepo/demos/blob/main/sand.py): `sand.py`
- [Flocking simulation](https://github.com/naskarepo/demos/blob/main/flocking.py): `flocking.py`
- [Vortex simulation](https://github.com/naskarepo/demos/blob/main/vortex.py): `vortex.py`

### Shared utilities

- [Keyboard thread](https://github.com/naskarepo/demos/blob/main/utils/keyboard.py): `utils/keyboard.py`
- [Key decoder](https://github.com/naskarepo/demos/blob/main/utils/getKey.py): `utils/getKey.py`
- [2D map helpers](https://github.com/naskarepo/demos/blob/main/utils/map2d.py): `utils/map2d.py`
- [Frame buffer](https://github.com/naskarepo/demos/blob/main/utils/frameBuffer.py): `utils/frameBuffer.py`

### Terminal and input

- **Windows key input**
- **Terminal display**

### Other components

- **Keyboard user**

## Connections

- Keyboard user → Windows key input: presses keys
- Windows key input → Key decoder: provides key bytes
- Sand simulation → Keyboard thread: starts input thread
- Flocking simulation → Keyboard thread: starts input thread
- Vortex simulation → Keyboard thread: starts input thread
- Keyboard thread → Key decoder: reads keys
- Keyboard thread → Sand simulation: dispatches callback
- Keyboard thread → Flocking simulation: dispatches callback
- Keyboard thread → Vortex simulation: dispatches callback
- Sand simulation → 2D map helpers: creates and swaps
- Flocking simulation → 2D map helpers: creates map
- Vortex simulation → 2D map helpers: creates map
- Sand simulation → Frame buffer: draws frames
- Flocking simulation → Frame buffer: draws frames
- Vortex simulation → Frame buffer: draws frames
- Frame buffer → 2D map helpers: prints initial map
- 2D map helpers → Terminal display: prints map
- Frame buffer → Terminal display: prints changed cells