# upperstory/spintronics-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/upperstory/spintronics-simulator
- Repository: https://github.com/upperstory/spintronics-simulator

## Overview

Spintronics Simulator is a browser-based editor and simulator for spintronic circuits. A user works in the simulator UI, which creates and updates circuit parts and chains through the part manager; the parts use a physics world to model mechanical behavior. The repository also includes circuit-link loading and level selection in the main UI. The README gives little detail, and the backend entry points were not excerpted, so their persistence behavior and connections are not mapped.

Main entry points: [`public/part-manager.js`](https://github.com/upperstory/spintronics-simulator/blob/main/public/part-manager.js) (Part manager), [`public/parts/partbase.js`](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/partbase.js) (Part interaction base), [`public/spintronicssimulator.js`](https://github.com/upperstory/spintronics-simulator/blob/main/public/spintronicssimulator.js) (Simulator UI), [`public/parts/motor-part.js`](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/motor-part.js) (Motor part)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Editor workflow"]
  node_simulator["Simulator UI"]
  node_level["Level chooser"]
  node_buttons["Toggle controls<br/>[toggle-button.js]"]
end

subgraph group_construction["Circuit construction"]
  node_manager["Part manager<br/>[part-manager.js]"]
  node_chain["Chain editor<br/>[chain.js]"]
end

subgraph group_components["Circuit components"]
  node_base["Part interaction base<br/>[partbase.js]"]
  node_buttonpart["Button part<br/>[button-part.js]"]
  node_capacitor["Capacitor part<br/>[capacitor-part.js]"]
  node_diode["Diode part<br/>[diode-part.js]"]
  node_inductor["Inductor part<br/>[inductor-part.js]"]
  node_junction["Junction part<br/>[junction-part.js]"]
  node_levelchanger["Level changer"]
  node_motor["Motor part<br/>[motor-part.js]"]
  node_phonograph["Phonograph part<br/>[phonograph-part.js]"]
  node_resistor["Resistor part<br/>[resistor-part.js]"]
  node_tile["Tile part<br/>[tile-part.js]"]
  node_tileconnector["Tile connector"]
  node_transistor["Transistor part<br/>[transistor-part.js]"]
end

subgraph group_runtime["Simulation runtime"]
  node_physics["Physics engine<br/>[planck.js]"]
  node_linkstore[("Circuit link store")]
end

node_user(("Circuit designer"))

node_user -->|"edits circuit"| node_simulator
node_simulator -->|"delegates editing"| node_manager
node_simulator -->|"opens chooser"| node_level
node_simulator -->|"uses controls"| node_buttons
node_manager -->|"creates chains"| node_chain
node_manager -->|"uses base class"| node_base
node_manager -->|"creates parts"| node_buttonpart
node_manager -->|"creates parts"| node_capacitor
node_manager -->|"creates parts"| node_diode
node_manager -->|"creates parts"| node_inductor
node_manager -->|"creates parts"| node_junction
node_manager -->|"creates parts"| node_levelchanger
node_manager -->|"creates parts"| node_motor
node_manager -->|"creates parts"| node_phonograph
node_manager -->|"creates parts"| node_resistor
node_manager -->|"creates parts"| node_tile
node_manager -->|"creates parts"| node_tileconnector
node_manager -->|"creates parts"| node_transistor
node_buttonpart -->|"extends"| node_base
node_capacitor -->|"extends"| node_base
node_diode -->|"extends"| node_base
node_inductor -->|"extends"| node_base
node_junction -->|"extends"| node_base
node_levelchanger -->|"extends"| node_base
node_motor -->|"extends"| node_base
node_phonograph -->|"extends"| node_base
node_resistor -->|"extends"| node_base
node_tile -->|"extends"| node_base
node_tileconnector -->|"extends"| node_base
node_transistor -->|"extends"| node_base
node_manager -->|"creates joints"| node_physics
node_simulator -->|"creates world"| node_physics
node_motor -->|"uses reset control"| node_buttons
node_simulator -.->|"loads circuit link"| node_linkstore

click node_simulator "https://github.com/upperstory/spintronics-simulator/blob/main/public/spintronicssimulator.js"
click node_level "https://github.com/upperstory/spintronics-simulator/blob/main/public/popup-level-chooser.js"
click node_buttons "https://github.com/upperstory/spintronics-simulator/blob/main/public/toggle-button.js"
click node_manager "https://github.com/upperstory/spintronics-simulator/blob/main/public/part-manager.js"
click node_chain "https://github.com/upperstory/spintronics-simulator/blob/main/public/chain.js"
click node_base "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/partbase.js"
click node_buttonpart "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/button-part.js"
click node_capacitor "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/capacitor-part.js"
click node_diode "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/diode-part.js"
click node_inductor "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/inductor-part.js"
click node_junction "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/junction-part.js"
click node_levelchanger "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/level-changer-part.js"
click node_motor "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/motor-part.js"
click node_phonograph "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/phonograph-part.js"
click node_resistor "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/resistor-part.js"
click node_tile "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/tile-part.js"
click node_tileconnector "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/tile-connector-part.js"
click node_transistor "https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/transistor-part.js"
click node_physics "https://github.com/upperstory/spintronics-simulator/blob/main/public/planck.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_simulator,node_level,node_buttons toneBlue
class node_manager,node_chain toneAmber
class node_base,node_buttonpart,node_capacitor,node_diode,node_inductor,node_junction,node_levelchanger,node_motor,node_phonograph,node_resistor,node_tile,node_tileconnector,node_transistor toneMint
class node_physics,node_linkstore toneRose
class node_user toneIndigo
```

## Components

### Editor workflow

- [Simulator UI](https://github.com/upperstory/spintronics-simulator/blob/main/public/spintronicssimulator.js): `public/spintronicssimulator.js`
- [Level chooser](https://github.com/upperstory/spintronics-simulator/blob/main/public/popup-level-chooser.js): `public/popup-level-chooser.js`
- [Toggle controls](https://github.com/upperstory/spintronics-simulator/blob/main/public/toggle-button.js): `public/toggle-button.js`

### Circuit construction

- [Part manager](https://github.com/upperstory/spintronics-simulator/blob/main/public/part-manager.js): `public/part-manager.js`
- [Chain editor](https://github.com/upperstory/spintronics-simulator/blob/main/public/chain.js): `public/chain.js`

### Circuit components

- [Part interaction base](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/partbase.js): `public/parts/partbase.js`
- [Button part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/button-part.js): `public/parts/button-part.js`
- [Capacitor part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/capacitor-part.js): `public/parts/capacitor-part.js`
- [Diode part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/diode-part.js): `public/parts/diode-part.js`
- [Inductor part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/inductor-part.js): `public/parts/inductor-part.js`
- [Junction part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/junction-part.js): `public/parts/junction-part.js`
- [Level changer](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/level-changer-part.js): `public/parts/level-changer-part.js`
- [Motor part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/motor-part.js): `public/parts/motor-part.js`
- [Phonograph part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/phonograph-part.js): `public/parts/phonograph-part.js`
- [Resistor part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/resistor-part.js): `public/parts/resistor-part.js`
- [Tile part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/tile-part.js): `public/parts/tile-part.js`
- [Tile connector](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/tile-connector-part.js): `public/parts/tile-connector-part.js`
- [Transistor part](https://github.com/upperstory/spintronics-simulator/blob/main/public/parts/transistor-part.js): `public/parts/transistor-part.js`

### Simulation runtime

- [Physics engine](https://github.com/upperstory/spintronics-simulator/blob/main/public/planck.js): `public/planck.js`
- **Circuit link store**

### Other components

- **Circuit designer**

## Connections

- Circuit designer → Simulator UI: edits circuit (evidence: `README.md`)
- Simulator UI → Part manager: delegates editing (evidence: `public/spintronicssimulator.js`)
- Simulator UI → Level chooser: opens chooser (evidence: `public/spintronicssimulator.js`)
- Simulator UI → Toggle controls: uses controls (evidence: `public/spintronicssimulator.js`)
- Part manager → Chain editor: creates chains (evidence: `public/part-manager.js`)
- Part manager → Part interaction base: uses base class (evidence: `public/part-manager.js`)
- Part manager → Button part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Capacitor part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Diode part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Inductor part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Junction part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Level changer: creates parts (evidence: `public/part-manager.js`)
- Part manager → Motor part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Phonograph part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Resistor part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Tile part: creates parts (evidence: `public/part-manager.js`)
- Part manager → Tile connector: creates parts (evidence: `public/part-manager.js`)
- Part manager → Transistor part: creates parts (evidence: `public/part-manager.js`)
- Button part → Part interaction base: extends (evidence: `public/parts/button-part.js`)
- Capacitor part → Part interaction base: extends (evidence: `public/parts/capacitor-part.js`)
- Diode part → Part interaction base: extends (evidence: `public/parts/diode-part.js`)
- Inductor part → Part interaction base: extends (evidence: `public/parts/inductor-part.js`)
- Junction part → Part interaction base: extends (evidence: `public/parts/junction-part.js`)
- Level changer → Part interaction base: extends (evidence: `public/parts/level-changer-part.js`)
- Motor part → Part interaction base: extends (evidence: `public/parts/motor-part.js`)
- Phonograph part → Part interaction base: extends (evidence: `public/parts/phonograph-part.js`)
- Resistor part → Part interaction base: extends (evidence: `public/parts/resistor-part.js`)
- Tile part → Part interaction base: extends (evidence: `public/parts/tile-part.js`)
- Tile connector → Part interaction base: extends (evidence: `public/parts/tile-connector-part.js`)
- Transistor part → Part interaction base: extends (evidence: `public/parts/transistor-part.js`)
- Part manager → Physics engine: creates joints (evidence: `public/part-manager.js`)
- Simulator UI → Physics engine: creates world (evidence: `public/spintronicssimulator.js`)
- Motor part → Toggle controls: uses reset control (evidence: `public/parts/motor-part.js`)
- Simulator UI → Circuit link store: loads circuit link
