# naman-dua/stem-sandbox-engine architecture

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

- Interactive diagram: https://gitdiagram.com/naman-dua/stem-sandbox-engine
- Repository: https://github.com/naman-dua/stem-sandbox-engine

## Overview

PrecisionSTEM is a browser-based virtual physics laboratory. A learner works with a lesson’s controls and runs a simulation; the simulation controller advances lesson calculations, while scene and graph renderers present the resulting physics and history. The README also documents notebook, challenge, prediction, metrics, formula-HUD, and observation capabilities, represented by the corresponding modules where identifiable. The sampled source confirms the physics, state, and rendering boundaries, but not all UI wiring or feature-module interactions, so uncertain connections are omitted.

Main entry points: [`js/render/renderer.js`](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/render/renderer.js) (Scene Pipeline), [`js/simulationController.js`](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/simulationController.js) (Simulation Controller), [`js/AssignmentEngine.js`](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/AssignmentEngine.js) (Challenge Assignments), [`js/engine.js`](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/engine.js) (Physics Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation Runtime"]
  node_state["Application State<br/>[stateManager.js]"]
  node_controller["Simulation Controller"]
  node_engine["Physics Engine<br/>[engine.js]"]
end

subgraph group_lessons["Lessons and Rendering"]
  node_lesson["Friction Lesson<br/>[friction.js]"]
  node_pipeline["Scene Pipeline<br/>[renderer.js]"]
  node_camera["Camera<br/>[camera.js]"]
  node_canvas["Canvas Renderers<br/>[blockRenderer.js]"]
  node_graph["Time-Series Graph<br/>[graphEngine.js]"]
end

subgraph group_learning["Learning Features"]
  node_metrics["Physics Metrics"]
  node_dashboard["Graph Dashboard<br/>[GraphDashboard.js]"]
  node_notebook["Lab Notebook"]
  node_reflection["Observation Panels<br/>[ReflectionPanel.js]"]
  node_guided["Guided Experiments"]
  node_assignments["Challenge Assignments"]
  node_progress["Progress Tracking<br/>[ProgressModel.js]"]
  node_comparison["Experiment Comparison"]
  node_replay["Simulation Replay<br/>[ReplaySystem.js]"]
  node_presentation["Presentation Mode"]
end

subgraph group_platform["Application Services"]
  node_bootstrap["Bootstrap<br/>[bootstrap.js]"]
  node_ui["UI Bridge<br/>[uiBridge.js]"]
  node_loader["Lesson Loader<br/>[lessonLoader.js]"]
  node_validator["Manifest Validator"]
  node_registry["Module Registry<br/>[ModuleRegistry.js]"]
  node_register["Module Registration<br/>[registerModules.js]"]
  node_error["Error Handling<br/>[ErrorHandler.js]"]
  node_events["Event Bus<br/>[EventBus.js]"]
  node_store[("Data Store<br/>[DataStore.js]")]
end

node_learner(("Learner"))

node_controller -->|"ticks or runs"| node_engine
node_engine -->|"calls calculations"| node_lesson
node_pipeline -->|"builds scene"| node_lesson
node_pipeline -->|"draws scene"| node_canvas
node_pipeline -->|"projects coordinates"| node_camera
node_ui -->|"supplies canvas context"| node_graph
node_controller -->|"validates physics"| node_error
node_assignments -->|"subscribes and publishes"| node_events
node_assignments -->|"loads and saves"| node_store

click node_bootstrap "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/bootstrap.js"
click node_ui "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/uiBridge.js"
click node_loader "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/lessonLoader.js"
click node_validator "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/manifestValidator.js"
click node_registry "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ModuleRegistry.js"
click node_register "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/registerModules.js"
click node_state "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/stateManager.js"
click node_controller "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/simulationController.js"
click node_engine "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/engine.js"
click node_lesson "https://github.com/naman-dua/stem-sandbox-engine/blob/main/lessons/friction.js"
click node_pipeline "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/render/renderer.js"
click node_camera "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/camera.js"
click node_canvas "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/blockRenderer.js"
click node_graph "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/graphEngine.js"
click node_error "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ErrorHandler.js"
click node_metrics "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/MeasurementTools.js"
click node_dashboard "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/GraphDashboard.js"
click node_notebook "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/SmartLabNotebook.js"
click node_reflection "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ReflectionPanel.js"
click node_guided "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/GuidedExperiment.js"
click node_assignments "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/AssignmentEngine.js"
click node_progress "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ProgressModel.js"
click node_comparison "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ExperimentComparison.js"
click node_replay "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ReplaySystem.js"
click node_presentation "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/PresentationMode.js"
click node_events "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/EventBus.js"
click node_store "https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/DataStore.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_state,node_controller,node_engine toneBlue
class node_lesson,node_pipeline,node_camera,node_canvas,node_graph toneAmber
class node_metrics,node_dashboard,node_notebook,node_reflection,node_guided,node_assignments,node_progress,node_comparison,node_replay,node_presentation toneMint
class node_bootstrap,node_ui,node_loader,node_validator,node_registry,node_register,node_error,node_events,node_store toneRose
class node_learner toneIndigo
```

## Components

### Simulation Runtime

- [Application State](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/stateManager.js): `js/stateManager.js`
- [Simulation Controller](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/simulationController.js): `js/simulationController.js`
- [Physics Engine](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/engine.js): `js/engine.js`

### Lessons and Rendering

- [Friction Lesson](https://github.com/naman-dua/stem-sandbox-engine/blob/main/lessons/friction.js): `lessons/friction.js`
- [Scene Pipeline](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/render/renderer.js): `js/render/renderer.js`
- [Camera](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/camera.js): `js/camera.js`
- [Canvas Renderers](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/blockRenderer.js): `js/blockRenderer.js`
- [Time-Series Graph](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/graphEngine.js): `js/graphEngine.js`

### Learning Features

- [Physics Metrics](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/MeasurementTools.js): `js/MeasurementTools.js`
- [Graph Dashboard](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/GraphDashboard.js): `js/GraphDashboard.js`
- [Lab Notebook](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/SmartLabNotebook.js): `js/SmartLabNotebook.js`
- [Observation Panels](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ReflectionPanel.js): `js/ReflectionPanel.js`
- [Guided Experiments](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/GuidedExperiment.js): `js/GuidedExperiment.js`
- [Challenge Assignments](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/AssignmentEngine.js): `js/AssignmentEngine.js`
- [Progress Tracking](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ProgressModel.js): `js/ProgressModel.js`
- [Experiment Comparison](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ExperimentComparison.js): `js/ExperimentComparison.js`
- [Simulation Replay](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ReplaySystem.js): `js/ReplaySystem.js`
- [Presentation Mode](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/PresentationMode.js): `js/PresentationMode.js`

### Application Services

- [Bootstrap](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/bootstrap.js): `js/bootstrap.js`
- [UI Bridge](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/uiBridge.js): `js/uiBridge.js`
- [Lesson Loader](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/lessonLoader.js): `js/lessonLoader.js`
- [Manifest Validator](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/manifestValidator.js): `js/manifestValidator.js`
- [Module Registry](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ModuleRegistry.js): `js/ModuleRegistry.js`
- [Module Registration](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/registerModules.js): `js/registerModules.js`
- [Error Handling](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/ErrorHandler.js): `js/ErrorHandler.js`
- [Event Bus](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/EventBus.js): `js/EventBus.js`
- [Data Store](https://github.com/naman-dua/stem-sandbox-engine/blob/main/js/DataStore.js): `js/DataStore.js`

### Other components

- **Learner**

## Connections

- Simulation Controller → Physics Engine: ticks or runs
- Physics Engine → Friction Lesson: calls calculations
- Scene Pipeline → Friction Lesson: builds scene
- Scene Pipeline → Canvas Renderers: draws scene
- Scene Pipeline → Camera: projects coordinates
- UI Bridge → Time-Series Graph: supplies canvas context
- Simulation Controller → Error Handling: validates physics
- Challenge Assignments → Event Bus: subscribes and publishes
- Challenge Assignments → Data Store: loads and saves