# winola-whu/geoscratch architecture

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

- Interactive diagram: https://gitdiagram.com/winola-whu/geoscratch
- Repository: https://github.com/winola-whu/geoscratch

## Overview

GeoScratch lets learners compose geometric and linear-algebra concepts as Blockly programs and view the resulting 3D objects. The main flow runs from the workspace and block toolbox through registered block definitions and generated execution, then synchronizes objects to the Three.js scene; users can also load examples, manage object variables, and export/import workspaces. The graph preserves documented capability areas. Relationships are limited to visible imports/calls and explicit README claims; unsampled block implementations are represented by their exact directories.

Main entry points: [`src/components/BlocksCanvas/BlocksCanvas.jsx`](https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/BlocksCanvas.jsx) (Blockly canvas), [`src/layout/Layout.jsx`](https://github.com/winola-whu/geoscratch/blob/main/src/layout/Layout.jsx) (Application layout), [`src/components/Header/Header.jsx`](https://github.com/winola-whu/geoscratch/blob/main/src/components/Header/Header.jsx) (Header controls), [`src/store/useWorkspaceStore.js`](https://github.com/winola-whu/geoscratch/blob/main/src/store/useWorkspaceStore.js) (Workspace state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace authoring"]
  node_blockcanvas["Blockly canvas<br/>[BlocksCanvas.jsx]"]
  node_workspacecore["Workspace setup<br/>[Workspace.jsx]"]
  node_toolbox["Block toolbox"]
  node_registry["Block registry<br/>[BlockRegistry.js]"]
  node_dialog["Object variable dialog"]
  node_serialization["Workspace import/export<br/>[serialization.js]"]
  node_examples["Example workspace loader<br/>[applyExampleXml.js]"]
end

subgraph group_math["Geometry and math"]
  node_geometry["Geometric constructions"]
  node_variables["3D object variables"]
  node_primitives["Linear algebra primitives"]
  node_operators["Linear algebra operators"]
  node_measurements["Measurements and debug"]
end

subgraph group_execution["Execution and state"]
  node_callbacks["Blockly callbacks<br/>[callbacks.js]"]
  node_runner["Run and synchronize<br/>[runAndSync.js]"]
  node_generator["Code generation<br/>[generateAndRun.js]"]
  node_workspace_state["Workspace state"]
  node_three_state["Three.js object state<br/>[useThreeStore.js]"]
  node_scene_state["Scene render state<br/>[useSceneStore.js]"]
end

subgraph group_visualization["3D visualization"]
  node_scene["Interactive 3D scene<br/>[Scene3D.jsx]"]
end

subgraph group_experience["User controls"]
  node_layout["Application layout<br/>[Layout.jsx]"]
  node_header["Header controls<br/>[Header.jsx]"]
  node_guides["Guides<br/>[GuidePopup.jsx]"]
  node_title["Workspace title<br/>[Title.jsx]"]
end

node_learner(("Learner"))

node_learner -->|"uses controls"| node_header
node_learner -->|"edits blocks"| node_blockcanvas
node_layout -->|"renders"| node_header
node_layout -->|"renders"| node_blockcanvas
node_layout -->|"renders"| node_scene
node_layout -->|"commits objects"| node_scene_state
node_layout -->|"sets example XML"| node_workspace_state
node_header -->|"renders"| node_guides
node_header -->|"renders"| node_title
node_header -->|"imports and exports"| node_serialization
node_header -->|"reads workspace"| node_workspace_state
node_blockcanvas -->|"initializes"| node_workspacecore
node_workspacecore -->|"configures"| node_toolbox
node_blockcanvas -->|"creates"| node_registry
node_blockcanvas -->|"registers definitions"| node_geometry
node_blockcanvas -->|"registers definitions"| node_variables
node_blockcanvas -->|"registers definitions"| node_primitives
node_blockcanvas -->|"registers definitions"| node_operators
node_blockcanvas -->|"registers definitions"| node_measurements
node_blockcanvas -->|"registers callbacks"| node_callbacks
node_blockcanvas -->|"renders"| node_dialog
node_dialog -.->|"uses workspace"| node_workspace_state
node_blockcanvas -->|"sets workspace"| node_workspace_state
node_blockcanvas -->|"runs workspace"| node_runner
node_runner -->|"invokes"| node_generator
node_generator -->|"updates objects"| node_three_state
node_runner -->|"reads objects"| node_three_state
node_blockcanvas -->|"applies XML"| node_examples
node_serialization -->|"reads workspace"| node_workspace_state
node_layout -->|"passes rendered objects"| node_scene
node_scene -->|"shows 3D scene"| node_learner
node_blockcanvas -->|"provides visual coding"| node_learner
node_geometry -->|"offers constructions"| node_learner
node_operators -->|"offers math concepts"| node_learner

click node_layout "https://github.com/winola-whu/geoscratch/blob/main/src/layout/Layout.jsx"
click node_header "https://github.com/winola-whu/geoscratch/blob/main/src/components/Header/Header.jsx"
click node_guides "https://github.com/winola-whu/geoscratch/blob/main/src/components/GuidePopup.jsx"
click node_title "https://github.com/winola-whu/geoscratch/blob/main/src/components/Title.jsx"
click node_blockcanvas "https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/BlocksCanvas.jsx"
click node_workspacecore "https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/core/Workspace.jsx"
click node_toolbox "https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/toolbox/BlocksToolboxDefinition.jsx"
click node_registry "https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/state/BlockRegistry.js"
click node_dialog "https://github.com/winola-whu/geoscratch/blob/main/src/components/CreateObj3DDiaglog.jsx"
click node_geometry "https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/geometric"
click node_variables "https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/geometricVariables"
click node_primitives "https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/linalgPrimitives"
click node_operators "https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/linalgOperators"
click node_measurements "https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/measurements"
click node_callbacks "https://github.com/winola-whu/geoscratch/blob/main/src/utils/callbacks.js"
click node_runner "https://github.com/winola-whu/geoscratch/blob/main/src/utils/runAndSync.js"
click node_generator "https://github.com/winola-whu/geoscratch/blob/main/src/utils/generateAndRun.js"
click node_workspace_state "https://github.com/winola-whu/geoscratch/blob/main/src/store/useWorkspaceStore.js"
click node_three_state "https://github.com/winola-whu/geoscratch/blob/main/src/store/useThreeStore.js"
click node_scene_state "https://github.com/winola-whu/geoscratch/blob/main/src/store/useSceneStore.js"
click node_serialization "https://github.com/winola-whu/geoscratch/blob/main/src/utils/serialization.js"
click node_examples "https://github.com/winola-whu/geoscratch/blob/main/src/utils/applyExampleXml.js"
click node_scene "https://github.com/winola-whu/geoscratch/blob/main/src/components/Scene3D/Scene3D.jsx"

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_blockcanvas,node_workspacecore,node_toolbox,node_registry,node_dialog,node_serialization,node_examples toneBlue
class node_geometry,node_variables,node_primitives,node_operators,node_measurements toneAmber
class node_callbacks,node_runner,node_generator,node_workspace_state,node_three_state,node_scene_state toneMint
class node_scene toneRose
class node_layout,node_header,node_guides,node_title,node_learner toneIndigo
```

## Components

### Workspace authoring

- [Blockly canvas](https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/BlocksCanvas.jsx): `src/components/BlocksCanvas/BlocksCanvas.jsx`
- [Workspace setup](https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/core/Workspace.jsx): `src/components/BlocksCanvas/core/Workspace.jsx`
- [Block toolbox](https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/toolbox/BlocksToolboxDefinition.jsx): `src/components/BlocksCanvas/toolbox/BlocksToolboxDefinition.jsx`
- [Block registry](https://github.com/winola-whu/geoscratch/blob/main/src/components/BlocksCanvas/state/BlockRegistry.js): `src/components/BlocksCanvas/state/BlockRegistry.js`
- [Object variable dialog](https://github.com/winola-whu/geoscratch/blob/main/src/components/CreateObj3DDiaglog.jsx): `src/components/CreateObj3DDiaglog.jsx`
- [Workspace import/export](https://github.com/winola-whu/geoscratch/blob/main/src/utils/serialization.js): `src/utils/serialization.js`
- [Example workspace loader](https://github.com/winola-whu/geoscratch/blob/main/src/utils/applyExampleXml.js): `src/utils/applyExampleXml.js`

### Geometry and math

- [Geometric constructions](https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/geometric): `src/components/BlocksCanvas/blocks/geometric`
- [3D object variables](https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/geometricVariables): `src/components/BlocksCanvas/blocks/geometricVariables`
- [Linear algebra primitives](https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/linalgPrimitives): `src/components/BlocksCanvas/blocks/linalgPrimitives`
- [Linear algebra operators](https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/linalgOperators): `src/components/BlocksCanvas/blocks/linalgOperators`
- [Measurements and debug](https://github.com/winola-whu/geoscratch/tree/main/src/components/BlocksCanvas/blocks/measurements): `src/components/BlocksCanvas/blocks/measurements`

### Execution and state

- [Blockly callbacks](https://github.com/winola-whu/geoscratch/blob/main/src/utils/callbacks.js): `src/utils/callbacks.js`
- [Run and synchronize](https://github.com/winola-whu/geoscratch/blob/main/src/utils/runAndSync.js): `src/utils/runAndSync.js`
- [Code generation](https://github.com/winola-whu/geoscratch/blob/main/src/utils/generateAndRun.js): `src/utils/generateAndRun.js`
- [Workspace state](https://github.com/winola-whu/geoscratch/blob/main/src/store/useWorkspaceStore.js): `src/store/useWorkspaceStore.js`
- [Three.js object state](https://github.com/winola-whu/geoscratch/blob/main/src/store/useThreeStore.js): `src/store/useThreeStore.js`
- [Scene render state](https://github.com/winola-whu/geoscratch/blob/main/src/store/useSceneStore.js): `src/store/useSceneStore.js`

### 3D visualization

- [Interactive 3D scene](https://github.com/winola-whu/geoscratch/blob/main/src/components/Scene3D/Scene3D.jsx): `src/components/Scene3D/Scene3D.jsx`

### User controls

- [Application layout](https://github.com/winola-whu/geoscratch/blob/main/src/layout/Layout.jsx): `src/layout/Layout.jsx`
- [Header controls](https://github.com/winola-whu/geoscratch/blob/main/src/components/Header/Header.jsx): `src/components/Header/Header.jsx`
- [Guides](https://github.com/winola-whu/geoscratch/blob/main/src/components/GuidePopup.jsx): `src/components/GuidePopup.jsx`
- [Workspace title](https://github.com/winola-whu/geoscratch/blob/main/src/components/Title.jsx): `src/components/Title.jsx`

### Other components

- **Learner**

## Connections

- Learner → Header controls: uses controls
- Learner → Blockly canvas: edits blocks
- Application layout → Header controls: renders (evidence: `src/layout/Layout.jsx`)
- Application layout → Blockly canvas: renders (evidence: `src/layout/Layout.jsx`)
- Application layout → Interactive 3D scene: renders (evidence: `src/layout/Layout.jsx`)
- Application layout → Scene render state: commits objects (evidence: `src/layout/Layout.jsx`)
- Application layout → Workspace state: sets example XML (evidence: `src/layout/Layout.jsx`)
- Header controls → Guides: renders (evidence: `src/components/Header/Header.jsx`)
- Header controls → Workspace title: renders (evidence: `src/components/Header/Header.jsx`)
- Header controls → Workspace import/export: imports and exports (evidence: `src/components/Header/Header.jsx`)
- Header controls → Workspace state: reads workspace (evidence: `src/components/Header/Header.jsx`)
- Blockly canvas → Workspace setup: initializes (evidence: `src/components/BlocksCanvas/BlocksCanvas.jsx`)
- Workspace setup → Block toolbox: configures (evidence: `src/components/BlocksCanvas/core/Workspace.jsx`)
- Blockly canvas → Block registry: creates (evidence: `src/components/BlocksCanvas/BlocksCanvas.jsx`)
- Blockly canvas → Geometric constructions: registers definitions
- Blockly canvas → 3D object variables: registers definitions
- Blockly canvas → Linear algebra primitives: registers definitions
- Blockly canvas → Linear algebra operators: registers definitions
- Blockly canvas → Measurements and debug: registers definitions
- Blockly canvas → Blockly callbacks: registers callbacks (evidence: `src/components/BlocksCanvas/BlocksCanvas.jsx`)
- Blockly canvas → Object variable dialog: renders (evidence: `src/components/BlocksCanvas/BlocksCanvas.jsx`)
- Object variable dialog → Workspace state: uses workspace
- Blockly canvas → Workspace state: sets workspace (evidence: `src/components/BlocksCanvas/BlocksCanvas.jsx`)
- Blockly canvas → Run and synchronize: runs workspace (evidence: `src/components/BlocksCanvas/BlocksCanvas.jsx`)
- Run and synchronize → Code generation: invokes (evidence: `src/utils/runAndSync.js`)
- Code generation → Three.js object state: updates objects (evidence: `src/utils/generateAndRun.js`)
- Run and synchronize → Three.js object state: reads objects (evidence: `src/utils/runAndSync.js`)
- Blockly canvas → Example workspace loader: applies XML (evidence: `src/components/BlocksCanvas/BlocksCanvas.jsx`)
- Workspace import/export → Workspace state: reads workspace (evidence: `src/utils/serialization.js`)
- Application layout → Interactive 3D scene: passes rendered objects (evidence: `src/layout/Layout.jsx`)
- Interactive 3D scene → Learner: shows 3D scene (evidence: `README.md`)
- Blockly canvas → Learner: provides visual coding (evidence: `README.md`)
- Geometric constructions → Learner: offers constructions (evidence: `README.md`)
- Linear algebra operators → Learner: offers math concepts (evidence: `README.md`)