# akbarsheikh-debug/wondersnap architecture

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

- Interactive diagram: https://gitdiagram.com/akbarsheikh-debug/wondersnap
- Repository: https://github.com/akbarsheikh-debug/wondersnap

## Overview

WonderSnap is a browser-based, gesture-controlled 3D particle model viewer. The main workflow is webcam hand landmarks → gesture/state interpretation → model selection and point-cloud construction → GPU animation and rendering. The app also supports keyboard/mouse input, model-part selection and exploded views, quiz and cut-away modes, voice commands, and video recording. The source excerpts show the main orchestration and several module dependencies; README statements support additional capabilities whose internal wiring was not sampled.

Main entry points: [`src/models/catalog.js`](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/catalog.js) (Model catalog), [`src/app.js`](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/app.js) (App orchestration), [`src/lib/sampling.js`](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/sampling.js) (Point sampling), [`src/gl/renderer.js`](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/gl/renderer.js) (WebGL renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Input and interaction"]
  node_handtracking["Hand tracking<br/>[hands.js]"]
  node_gesture["Gesture classifiers<br/>[gestures.js]"]
  node_controller["Gesture controller<br/>[controller.js]"]
  node_state["Viewer state<br/>[state.js]"]
  node_app["App orchestration<br/>[app.js]"]
end

subgraph group_models["Procedural models"]
  node_catalog["Model catalog<br/>[catalog.js]"]
  node_wonders["Wonders<br/>[wonders.js]"]
  node_anatomy["Anatomy<br/>[anatomy.js]"]
  node_anatomy2["More anatomy<br/>[anatomy2.js]"]
  node_body["Human body<br/>[body.js]"]
  node_biology["Biology<br/>[biology.js]"]
  node_engines["Engines<br/>[engines.js]"]
  node_vehicles["Vehicles<br/>[vehicles.js]"]
  node_machines["Machines<br/>[machines.js]"]
  node_sampling["Point sampling<br/>[sampling.js]"]
  node_shapes["Shape helpers<br/>[shapes.js]"]
  node_vec["Vector math<br/>[vec.js]"]
  node_rng["Deterministic RNG<br/>[rng.js]"]
end

subgraph group_engine["Particle rendering"]
  node_renderer["WebGL renderer<br/>[renderer.js]"]
  node_shaders["GPU shaders<br/>[shaders.js]"]
  node_simref["Particle seeds<br/>[simRef.js]"]
end

subgraph group_features["Viewer features"]
  node_features["Voice and recording<br/>[features.js]"]
end

node_user(("Viewer"))
node_camera(("Webcam"))
node_mediapipe["MediaPipe runtime"]

node_user -->|"controls viewer"| node_app
node_camera -->|"provides video"| node_handtracking
node_mediapipe -->|"tracks landmarks"| node_handtracking
node_handtracking -.->|"supplies hands"| node_app
node_app -->|"processes input"| node_controller
node_controller -->|"classifies poses"| node_gesture
node_controller -->|"updates state"| node_state
node_app -->|"builds models"| node_catalog
node_catalog -->|"uses definitions"| node_wonders
node_catalog -->|"uses definitions"| node_anatomy
node_catalog -->|"uses definitions"| node_anatomy2
node_catalog -->|"uses definitions"| node_body
node_catalog -->|"uses definitions"| node_biology
node_catalog -->|"uses definitions"| node_engines
node_catalog -->|"uses definitions"| node_vehicles
node_catalog -->|"uses definitions"| node_machines
node_catalog -->|"samples parts"| node_sampling
node_sampling -->|"uses randomness"| node_rng
node_sampling -->|"uses vector math"| node_vec
node_shapes -->|"builds primitives"| node_sampling
node_shapes -->|"uses vector math"| node_vec
node_app -->|"creates renderer"| node_renderer
node_renderer -->|"runs shaders"| node_shaders
node_renderer -->|"creates particle seeds"| node_simref
node_app -->|"parses voice commands"| node_features
node_app -->|"supports voice and recording"| node_features
node_app -->|"renders interactive scene"| node_renderer

click node_handtracking "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/hands.js"
click node_gesture "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/gestures.js"
click node_controller "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/controller.js"
click node_state "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/state.js"
click node_app "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/app.js"
click node_catalog "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/catalog.js"
click node_wonders "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/wonders.js"
click node_anatomy "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/anatomy.js"
click node_anatomy2 "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/anatomy2.js"
click node_body "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/body.js"
click node_biology "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/biology.js"
click node_engines "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/engines.js"
click node_vehicles "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/vehicles.js"
click node_machines "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/machines.js"
click node_sampling "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/sampling.js"
click node_shapes "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/shapes.js"
click node_vec "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/vec.js"
click node_rng "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/rng.js"
click node_renderer "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/gl/renderer.js"
click node_shaders "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/gl/shaders.js"
click node_simref "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/simRef.js"
click node_features "https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/features.js"

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_handtracking,node_gesture,node_controller,node_state,node_app,node_user toneBlue
class node_catalog,node_wonders,node_anatomy,node_anatomy2,node_body,node_biology,node_engines,node_vehicles,node_machines,node_sampling,node_shapes,node_vec,node_rng toneAmber
class node_renderer,node_shaders,node_simref,node_mediapipe toneMint
class node_features toneRose
class node_camera toneIndigo
```

## Components

### Input and interaction

- [Hand tracking](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/hands.js): `src/hands.js`
- [Gesture classifiers](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/gestures.js): `src/logic/gestures.js`
- [Gesture controller](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/controller.js): `src/logic/controller.js`
- [Viewer state](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/state.js): `src/logic/state.js`
- [App orchestration](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/app.js): `src/app.js`

### Procedural models

- [Model catalog](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/catalog.js): `src/models/catalog.js`
- [Wonders](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/wonders.js): `src/models/wonders.js`
- [Anatomy](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/anatomy.js): `src/models/anatomy.js`
- [More anatomy](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/anatomy2.js): `src/models/anatomy2.js`
- [Human body](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/body.js): `src/models/body.js`
- [Biology](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/biology.js): `src/models/biology.js`
- [Engines](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/engines.js): `src/models/engines.js`
- [Vehicles](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/vehicles.js): `src/models/vehicles.js`
- [Machines](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/models/machines.js): `src/models/machines.js`
- [Point sampling](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/sampling.js): `src/lib/sampling.js`
- [Shape helpers](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/shapes.js): `src/lib/shapes.js`
- [Vector math](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/vec.js): `src/lib/vec.js`
- [Deterministic RNG](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/lib/rng.js): `src/lib/rng.js`

### Particle rendering

- [WebGL renderer](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/gl/renderer.js): `src/gl/renderer.js`
- [GPU shaders](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/gl/shaders.js): `src/gl/shaders.js`
- [Particle seeds](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/logic/simRef.js): `src/logic/simRef.js`

### Viewer features

- [Voice and recording](https://github.com/akbarsheikh-debug/wondersnap/blob/main/src/features.js): `src/features.js`

### Other components

- **Viewer**
- **Webcam**
- **MediaPipe runtime**

## Connections

- Viewer → App orchestration: controls viewer (evidence: `README.md`)
- Webcam → Hand tracking: provides video (evidence: `README.md`)
- MediaPipe runtime → Hand tracking: tracks landmarks (evidence: `README.md`)
- Hand tracking → App orchestration: supplies hands (evidence: `src/app.js`)
- App orchestration → Gesture controller: processes input (evidence: `src/app.js`)
- Gesture controller → Gesture classifiers: classifies poses (evidence: `src/logic/controller.js`)
- Gesture controller → Viewer state: updates state (evidence: `src/logic/controller.js`)
- App orchestration → Model catalog: builds models (evidence: `src/app.js`)
- Model catalog → Wonders: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → Anatomy: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → More anatomy: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → Human body: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → Biology: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → Engines: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → Vehicles: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → Machines: uses definitions (evidence: `src/models/catalog.js`)
- Model catalog → Point sampling: samples parts (evidence: `src/models/catalog.js`)
- Point sampling → Deterministic RNG: uses randomness (evidence: `src/lib/sampling.js`)
- Point sampling → Vector math: uses vector math (evidence: `src/lib/sampling.js`)
- Shape helpers → Point sampling: builds primitives (evidence: `src/lib/shapes.js`)
- Shape helpers → Vector math: uses vector math (evidence: `src/lib/shapes.js`)
- App orchestration → WebGL renderer: creates renderer (evidence: `src/app.js`)
- WebGL renderer → GPU shaders: runs shaders (evidence: `src/gl/renderer.js`)
- WebGL renderer → Particle seeds: creates particle seeds (evidence: `src/gl/renderer.js`)
- App orchestration → Voice and recording: parses voice commands (evidence: `src/app.js`)
- App orchestration → Voice and recording: supports voice and recording (evidence: `README.md`)
- App orchestration → WebGL renderer: renders interactive scene (evidence: `README.md`)
