# abektes/lumaform-orb architecture

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

- Interactive diagram: https://gitdiagram.com/abektes/lumaform-orb
- Repository: https://github.com/abektes/lumaform-orb

## Overview

Lumaform Orb pairs a WebGL orb runtime with a browser-based exploration studio. The main workflow is: an artist selects a preset or engine, adjusts and compares animated looks, then exports a configuration or captures a finding. The runtime applies that configuration to an engine and renders the orb; the studio adds variation grids, motion modulation, rehearsal, and capture. The README documents these capabilities, while sampled source confirms startup, engine registration, and engine notifications; some subsystem wiring is therefore represented only where documented.

Main entry points: [`packages/studio/src/ui/studio-ui.js`](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/ui/studio-ui.js) (Studio UI), [`packages/studio/src/core/store.js`](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/store.js) (Studio state), [`packages/studio/src/main.js`](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/main.js) (Studio startup), [`packages/orb/src/core/runtime.js`](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/core/runtime.js) (Render runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_studio["Studio"]
  node_studio_main["Studio startup<br/>[main.js]"]
  node_studio_ui["Studio UI<br/>[studio-ui.js]"]
  node_studio_state["Studio state<br/>[store.js]"]
  node_studio_core["Studio controller<br/>[studio.js]"]
  node_engine_registration["Engine registration"]
end

subgraph group_runtime["Orb runtime"]
  node_create_orb["Orb entry point<br/>[create-orb.js]"]
  node_runtime_loop["Render runtime<br/>[runtime.js]"]
  node_engine_catalog["Engine schemas<br/>[engine-catalog.js]"]
  node_engine_factories["Shader engines<br/>[index.js]"]
  node_engine_notify["Engine notifications<br/>[engine-notify.js]"]
end

subgraph group_exploration["Look exploration"]
  node_presets["Preset library<br/>[preset-library.js]"]
  node_variation["Variation tools<br/>[variation-grid.js]"]
  node_motion_lab["Motion Lab<br/>[studio.js]"]
  node_comparison["Look comparison<br/>[ab-compare.js]"]
  node_rehearsal["Rehearsal sequence<br/>[sequence.js]"]
end

subgraph group_capture["Capture and audio"]
  node_capture_tools["Capture tools<br/>[clip-recorder.js]"]
  node_findings["Findings shelf<br/>[findings.js]"]
  node_audio_input["Microphone input<br/>[audio-input.js]"]
  node_audio_level["Audio level<br/>[audio-level.js]"]
end

node_artist(("Artist"))
node_webgl["WebGL canvas"]

node_artist -->|"uses"| node_studio_ui
node_studio_main -->|"creates"| node_studio_state
node_studio_main -->|"creates"| node_studio_core
node_studio_main -->|"mounts"| node_studio_ui
node_studio_main -->|"registers engines"| node_engine_registration
node_engine_registration -->|"pairs schemas"| node_engine_catalog
node_engine_registration -->|"loads factories"| node_engine_factories
node_studio_ui -->|"updates"| node_studio_state
node_studio_ui -->|"selects look"| node_studio_core
node_presets -->|"sets defaults"| node_studio_state
node_variation -->|"mutates parameters"| node_studio_state
node_motion_lab -->|"routes modulation"| node_studio_state
node_comparison -->|"swaps configs"| node_studio_state
node_rehearsal -->|"plays sequence"| node_studio_state
node_studio_core -->|"configures runtime"| node_create_orb
node_create_orb -->|"starts loop"| node_runtime_loop
node_runtime_loop -->|"runs engine"| node_engine_factories
node_runtime_loop -->|"dispatches events"| node_engine_notify
node_runtime_loop -->|"renders frames"| node_webgl
node_studio_ui -->|"captures clips"| node_capture_tools
node_studio_ui -->|"saves finding"| node_findings
node_studio_ui -->|"reads schemas"| node_engine_catalog
node_audio_input -.->|"analyzes signal"| node_audio_level
node_audio_level -.->|"supplies amplitude"| node_motion_lab

click node_studio_main "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/main.js"
click node_studio_ui "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/ui/studio-ui.js"
click node_studio_state "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/store.js"
click node_studio_core "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/studio.js"
click node_engine_registration "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/register-engines.js"
click node_presets "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/presets/preset-library.js"
click node_variation "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/variation-grid.js"
click node_motion_lab "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/studio.js"
click node_comparison "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/ab-compare.js"
click node_rehearsal "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/sequence.js"
click node_capture_tools "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/clip-recorder.js"
click node_findings "https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/findings.js"
click node_audio_input "https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/audio/audio-input.js"
click node_audio_level "https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/audio/audio-level.js"
click node_create_orb "https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/create-orb.js"
click node_runtime_loop "https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/core/runtime.js"
click node_engine_catalog "https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/engine-catalog.js"
click node_engine_factories "https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/engines/index.js"
click node_engine_notify "https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/core/engine-notify.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_studio_main,node_studio_ui,node_studio_state,node_studio_core,node_engine_registration toneBlue
class node_create_orb,node_runtime_loop,node_engine_catalog,node_engine_factories,node_engine_notify toneAmber
class node_presets,node_variation,node_motion_lab,node_comparison,node_rehearsal toneMint
class node_capture_tools,node_findings,node_audio_input,node_audio_level toneRose
class node_artist,node_webgl toneIndigo
```

## Components

### Studio

- [Studio startup](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/main.js): `packages/studio/src/main.js`
- [Studio UI](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/ui/studio-ui.js): `packages/studio/src/ui/studio-ui.js`
- [Studio state](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/store.js): `packages/studio/src/core/store.js`
- [Studio controller](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/studio.js): `packages/studio/src/core/studio.js`
- [Engine registration](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/register-engines.js): `packages/studio/src/core/register-engines.js`

### Orb runtime

- [Orb entry point](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/create-orb.js): `packages/orb/src/create-orb.js`
- [Render runtime](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/core/runtime.js): `packages/orb/src/core/runtime.js`
- [Engine schemas](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/engine-catalog.js): `packages/orb/src/engine-catalog.js`
- [Shader engines](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/engines/index.js): `packages/orb/src/engines/index.js`
- [Engine notifications](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/core/engine-notify.js): `packages/orb/src/core/engine-notify.js`

### Look exploration

- [Preset library](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/presets/preset-library.js): `packages/studio/src/presets/preset-library.js`
- [Variation tools](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/variation-grid.js): `packages/studio/src/core/variation-grid.js`
- [Motion Lab](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/studio.js): `packages/studio/src/core/studio.js`
- [Look comparison](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/ab-compare.js): `packages/studio/src/core/ab-compare.js`
- [Rehearsal sequence](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/sequence.js): `packages/studio/src/core/sequence.js`

### Capture and audio

- [Capture tools](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/clip-recorder.js): `packages/studio/src/core/clip-recorder.js`
- [Findings shelf](https://github.com/abektes/lumaform-orb/blob/main/packages/studio/src/core/findings.js): `packages/studio/src/core/findings.js`
- [Microphone input](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/audio/audio-input.js): `packages/orb/src/audio/audio-input.js`
- [Audio level](https://github.com/abektes/lumaform-orb/blob/main/packages/orb/src/audio/audio-level.js): `packages/orb/src/audio/audio-level.js`

### Other components

- **Artist**
- **WebGL canvas**

## Connections

- Artist → Studio UI: uses
- Studio startup → Studio state: creates
- Studio startup → Studio controller: creates
- Studio startup → Studio UI: mounts
- Studio startup → Engine registration: registers engines
- Engine registration → Engine schemas: pairs schemas
- Engine registration → Shader engines: loads factories
- Studio UI → Studio state: updates
- Studio UI → Studio controller: selects look
- Preset library → Studio state: sets defaults
- Variation tools → Studio state: mutates parameters
- Motion Lab → Studio state: routes modulation
- Look comparison → Studio state: swaps configs
- Rehearsal sequence → Studio state: plays sequence
- Studio controller → Orb entry point: configures runtime
- Orb entry point → Render runtime: starts loop
- Render runtime → Shader engines: runs engine
- Render runtime → Engine notifications: dispatches events
- Render runtime → WebGL canvas: renders frames
- Studio UI → Capture tools: captures clips
- Studio UI → Findings shelf: saves finding
- Studio UI → Engine schemas: reads schemas
- Microphone input → Audio level: analyzes signal
- Audio level → Motion Lab: supplies amplitude