# lersent001/orb architecture

> Architecture diagram of the GitHub repository lersent001/orb, 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/lersent001/orb
- Repository: https://github.com/lersent001/orb

## Overview

Liquid Orb Editor is a browser-based editor for animated liquid-glass orbs. Users choose a preset, adjust its parameters, preview the result as an orb or in a scene, and share configurations through the URL hash or export standalone Web and SwiftUI/Metal code. The core runtime maps editor state into WebGPU rendering; optional local audio modulates supported presets. The README documents these capabilities, while the sampled source confirms the app entry point, renderer setup, and audio handoff; some internal wiring is described only at the subsystem level.

Main entry points: [`src/App.tsx`](https://github.com/lersent001/orb/blob/main/src/App.tsx) (Editor app), [`src/orb-renderer.ts`](https://github.com/lersent001/orb/blob/main/src/orb-renderer.ts) (WebGPU renderer), [`src/AudioControls.tsx`](https://github.com/lersent001/orb/blob/main/src/AudioControls.tsx) (Audio controls), [`src/code-export.ts`](https://github.com/lersent001/orb/blob/main/src/code-export.ts) (Code exporters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Editor experience"]
  node_app["Editor app<br/>[App.tsx]"]
  node_controls["Audio controls<br/>[AudioControls.tsx]"]
  node_i18n["Editor localization<br/>[editor-i18n.ts]"]
  node_entry["React entry point<br/>[main.tsx]"]
end

subgraph group_model["Orb state"]
  node_presets["Preset definitions<br/>[presets.ts]"]
  node_orbstate["State transitions<br/>[orb-states.ts]"]
  node_uniforms["GPU parameter mapping<br/>[orb-uniforms.ts]"]
end

subgraph group_runtime["Rendering runtime"]
  node_renderer["WebGPU renderer<br/>[orb-renderer.ts]"]
  node_shader["Shader source<br/>[shader-source.ts]"]
  node_particles["Particle ribbon<br/>[particle-ribbon.ts]"]
  node_audio["Audio response<br/>[orb-audio.ts]"]
end

subgraph group_outputs["Sharing and exports"]
  node_exporter["Code exporters<br/>[code-export.ts]"]
end

subgraph group_ui["UI foundation"]
  node_ui["Toolcraft UI"]
end

node_user(("Editor user"))
node_webgpu{{"WebGPU device"}}
node_audioinput(("Local audio input"))
node_browserhash["Browser URL hash"]

node_user -->|"edits settings"| node_app
node_entry -->|"renders"| node_app
node_app -->|"selects preset"| node_presets
node_app -->|"resolves state"| node_orbstate
node_app -->|"creates renderer"| node_renderer
node_app -->|"configures audio"| node_controls
node_app -->|"localizes UI"| node_i18n
node_app -->|"renders controls"| node_ui
node_app -->|"reads and writes"| node_browserhash
node_app -->|"requests export"| node_exporter
node_audioinput -->|"provides audio"| node_controls
node_controls -->|"supplies bands"| node_audio
node_renderer -->|"reads modulation"| node_audio
node_renderer -->|"uses parameters"| node_orbstate
node_renderer -->|"maps parameters"| node_uniforms
node_renderer -->|"uses shader"| node_shader
node_renderer -->|"renders ribbon"| node_particles
node_renderer -->|"submits rendering"| node_webgpu
node_exporter -->|"exports parameters"| node_presets

click node_app "https://github.com/lersent001/orb/blob/main/src/App.tsx"
click node_controls "https://github.com/lersent001/orb/blob/main/src/AudioControls.tsx"
click node_i18n "https://github.com/lersent001/orb/blob/main/src/editor-i18n.ts"
click node_presets "https://github.com/lersent001/orb/blob/main/src/presets.ts"
click node_orbstate "https://github.com/lersent001/orb/blob/main/src/orb-states.ts"
click node_uniforms "https://github.com/lersent001/orb/blob/main/src/orb-uniforms.ts"
click node_renderer "https://github.com/lersent001/orb/blob/main/src/orb-renderer.ts"
click node_shader "https://github.com/lersent001/orb/blob/main/src/shader-source.ts"
click node_particles "https://github.com/lersent001/orb/blob/main/src/particle-ribbon.ts"
click node_audio "https://github.com/lersent001/orb/blob/main/src/orb-audio.ts"
click node_exporter "https://github.com/lersent001/orb/blob/main/src/code-export.ts"
click node_ui "https://github.com/lersent001/orb/tree/main/src/toolcraft/ui/components"
click node_entry "https://github.com/lersent001/orb/blob/main/src/main.tsx"

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_app,node_controls,node_i18n,node_entry,node_user,node_browserhash toneBlue
class node_presets,node_orbstate,node_uniforms toneAmber
class node_renderer,node_shader,node_particles,node_audio toneMint
class node_exporter toneRose
class node_ui,node_webgpu,node_audioinput toneIndigo
```

## Components

### Editor experience

- [Editor app](https://github.com/lersent001/orb/blob/main/src/App.tsx): `src/App.tsx`
- [Audio controls](https://github.com/lersent001/orb/blob/main/src/AudioControls.tsx): `src/AudioControls.tsx`
- [Editor localization](https://github.com/lersent001/orb/blob/main/src/editor-i18n.ts): `src/editor-i18n.ts`
- [React entry point](https://github.com/lersent001/orb/blob/main/src/main.tsx): `src/main.tsx`

### Orb state

- [Preset definitions](https://github.com/lersent001/orb/blob/main/src/presets.ts): `src/presets.ts`
- [State transitions](https://github.com/lersent001/orb/blob/main/src/orb-states.ts): `src/orb-states.ts`
- [GPU parameter mapping](https://github.com/lersent001/orb/blob/main/src/orb-uniforms.ts): `src/orb-uniforms.ts`

### Rendering runtime

- [WebGPU renderer](https://github.com/lersent001/orb/blob/main/src/orb-renderer.ts): `src/orb-renderer.ts`
- [Shader source](https://github.com/lersent001/orb/blob/main/src/shader-source.ts): `src/shader-source.ts`
- [Particle ribbon](https://github.com/lersent001/orb/blob/main/src/particle-ribbon.ts): `src/particle-ribbon.ts`
- [Audio response](https://github.com/lersent001/orb/blob/main/src/orb-audio.ts): `src/orb-audio.ts`

### Sharing and exports

- [Code exporters](https://github.com/lersent001/orb/blob/main/src/code-export.ts): `src/code-export.ts`

### UI foundation

- [Toolcraft UI](https://github.com/lersent001/orb/tree/main/src/toolcraft/ui/components): `src/toolcraft/ui/components`

### Other components

- **Editor user**
- **WebGPU device**
- **Local audio input**
- **Browser URL hash**

## Connections

- Editor user → Editor app: edits settings
- React entry point → Editor app: renders
- Editor app → Preset definitions: selects preset
- Editor app → State transitions: resolves state
- Editor app → WebGPU renderer: creates renderer
- Editor app → Audio controls: configures audio
- Editor app → Editor localization: localizes UI
- Editor app → Toolcraft UI: renders controls
- Editor app → Browser URL hash: reads and writes
- Editor app → Code exporters: requests export
- Local audio input → Audio controls: provides audio
- Audio controls → Audio response: supplies bands
- WebGPU renderer → Audio response: reads modulation
- WebGPU renderer → State transitions: uses parameters
- WebGPU renderer → GPU parameter mapping: maps parameters
- WebGPU renderer → Shader source: uses shader
- WebGPU renderer → Particle ribbon: renders ribbon
- WebGPU renderer → WebGPU device: submits rendering
- Code exporters → Preset definitions: exports parameters