# fefedu973/lumathread architecture

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

- Interactive diagram: https://gitdiagram.com/fefedu973/lumathread
- Repository: https://github.com/fefedu973/lumathread

## Overview

LumaThread is a React/WebGL luminous-filament renderer, with a documentation site and interactive configuration lab. The primary workflow is to configure a component, generate or follow a filament path, and render it with motion, material, interaction, and optional glass effects. The graph also includes the lab workflow and documented rendering capabilities. Some runtime and site subsystems are represented at their existing directory or module level because their implementation was not sampled.

Main entry points: [`src/runtime/HdrHeroWaveBackground.tsx`](https://github.com/fefedu973/lumathread/blob/main/src/runtime/HdrHeroWaveBackground.tsx) (Renderer runtime), [`src/runtime/geometry-controller.ts`](https://github.com/fefedu973/lumathread/blob/main/src/runtime/geometry-controller.ts) (Path geometry), [`src/runtime/draw-controller.ts`](https://github.com/fefedu973/lumathread/blob/main/src/runtime/draw-controller.ts) (Draw orchestration), [`site/features/lab/use-lab-controller.ts`](https://github.com/fefedu973/lumathread/blob/main/site/features/lab/use-lab-controller.ts) (Lab controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_api["Public exports<br/>[index.ts]"]
  node_component["Component API"]
  node_settings["Settings resolution"]
end

subgraph group_engine["Geometry and Interaction"]
  node_geometry["Path geometry"]
  node_pathmath["Path sampling<br/>[path-sampling.ts]"]
  node_propagation["Motion propagation<br/>[propagation.ts]"]
  node_follow["Pointer following"]
  node_disturbance["Filament disturbance"]
end

subgraph group_render["WebGL Rendering"]
  node_runtime["Renderer runtime"]
  node_draw["Draw orchestration<br/>[draw-controller.ts]"]
  node_pathrender["Path renderer<br/>[path-renderer.ts]"]
  node_sinerender["Sine renderer<br/>[sine-renderer.ts]"]
  node_glassrender["Glass and terrain"]
  node_resources["GPU resources"]
  node_shaders["WebGL programs<br/>[webgl-resources.ts]"]
  node_domglass["DOM glass tracking"]
end

subgraph group_site["Showcase and Lab"]
  node_siteentry["Site entry<br/>[main.tsx]"]
  node_home["Homepage showcase<br/>[home.tsx]"]
  node_demos["Live demos<br/>[showcase.tsx]"]
  node_labpage["Configuration lab<br/>[lab.tsx]"]
  node_labcontroller["Lab controller"]
  node_labmodel["Lab state model<br/>[initial-state.ts]"]
  node_labstage["Interactive stage<br/>[lab-stage.tsx]"]
  node_labcontrols["Lab controls"]
  node_apiinfo["API reference<br/>[api-reference.ts]"]
end

node_developer(("React developer"))
node_visitor(("Showcase visitor"))

node_developer -->|"imports"| node_api
node_api -->|"exports"| node_component
node_component -->|"resolves props"| node_settings
node_component -->|"renders"| node_runtime
node_runtime -->|"updates paths"| node_geometry
node_geometry -->|"samples paths"| node_pathmath
node_geometry -->|"builds motion"| node_propagation
node_runtime -->|"updates follow"| node_follow
node_geometry -->|"applies impulses"| node_disturbance
node_runtime -->|"draws frames"| node_draw
node_draw -->|"dispatches paths"| node_pathrender
node_draw -->|"dispatches sine"| node_sinerender
node_draw -->|"draws effects"| node_glassrender
node_pathrender -->|"uses resources"| node_resources
node_sinerender -->|"uses resources"| node_resources
node_glassrender -->|"uses resources"| node_resources
node_resources -->|"creates programs"| node_shaders
node_runtime -->|"tracks target"| node_domglass
node_visitor -->|"opens site"| node_siteentry
node_siteentry -->|"routes home"| node_home
node_home -->|"shows demos"| node_demos
node_home -->|"presents reference"| node_apiinfo
node_visitor -->|"opens lab"| node_labpage
node_labpage -->|"creates controller"| node_labcontroller
node_labcontroller -->|"uses state"| node_labmodel
node_labcontroller -->|"provides controls"| node_labcontrols
node_labcontroller -->|"configures stage"| node_labstage
node_labstage -->|"renders preview"| node_component

click node_api "https://github.com/fefedu973/lumathread/blob/main/src/index.ts"
click node_component "https://github.com/fefedu973/lumathread/blob/main/src/hero-wave-background.tsx"
click node_settings "https://github.com/fefedu973/lumathread/blob/main/src/config/resolved-settings.ts"
click node_runtime "https://github.com/fefedu973/lumathread/blob/main/src/runtime/HdrHeroWaveBackground.tsx"
click node_geometry "https://github.com/fefedu973/lumathread/blob/main/src/runtime/geometry-controller.ts"
click node_pathmath "https://github.com/fefedu973/lumathread/blob/main/src/geometry/path-sampling.ts"
click node_propagation "https://github.com/fefedu973/lumathread/blob/main/src/geometry/propagation.ts"
click node_follow "https://github.com/fefedu973/lumathread/blob/main/src/runtime/follow-controller.ts"
click node_disturbance "https://github.com/fefedu973/lumathread/blob/main/src/interaction/filament-disturbance.ts"
click node_draw "https://github.com/fefedu973/lumathread/blob/main/src/runtime/draw-controller.ts"
click node_pathrender "https://github.com/fefedu973/lumathread/blob/main/src/runtime/path-renderer.ts"
click node_sinerender "https://github.com/fefedu973/lumathread/blob/main/src/runtime/sine-renderer.ts"
click node_glassrender "https://github.com/fefedu973/lumathread/blob/main/src/runtime/glass-terrain-renderer.ts"
click node_resources "https://github.com/fefedu973/lumathread/blob/main/src/runtime/resource-manager.ts"
click node_shaders "https://github.com/fefedu973/lumathread/blob/main/src/rendering/webgl-resources.ts"
click node_domglass "https://github.com/fefedu973/lumathread/blob/main/src/runtime/use-glass-text-dom-target.ts"
click node_siteentry "https://github.com/fefedu973/lumathread/blob/main/site/main.tsx"
click node_home "https://github.com/fefedu973/lumathread/blob/main/site/pages/home.tsx"
click node_demos "https://github.com/fefedu973/lumathread/blob/main/site/components/demo/showcase.tsx"
click node_labpage "https://github.com/fefedu973/lumathread/blob/main/site/pages/lab.tsx"
click node_labcontroller "https://github.com/fefedu973/lumathread/blob/main/site/features/lab/use-lab-controller.ts"
click node_labmodel "https://github.com/fefedu973/lumathread/blob/main/site/features/lab/model/initial-state.ts"
click node_labstage "https://github.com/fefedu973/lumathread/blob/main/site/features/lab/stage/lab-stage.tsx"
click node_labcontrols "https://github.com/fefedu973/lumathread/blob/main/site/features/lab/controls/lab-control-panel.tsx"
click node_apiinfo "https://github.com/fefedu973/lumathread/blob/main/site/data/api-reference.ts"

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_api,node_component,node_settings toneBlue
class node_geometry,node_pathmath,node_propagation,node_follow,node_disturbance toneAmber
class node_runtime,node_draw,node_pathrender,node_sinerender,node_glassrender,node_resources,node_shaders,node_domglass toneMint
class node_siteentry,node_home,node_demos,node_labpage,node_labcontroller,node_labmodel,node_labstage,node_labcontrols,node_apiinfo toneRose
class node_developer,node_visitor toneIndigo
```

## Components

### Public API

- [Public exports](https://github.com/fefedu973/lumathread/blob/main/src/index.ts): `src/index.ts`
- [Component API](https://github.com/fefedu973/lumathread/blob/main/src/hero-wave-background.tsx): `src/hero-wave-background.tsx`
- [Settings resolution](https://github.com/fefedu973/lumathread/blob/main/src/config/resolved-settings.ts): `src/config/resolved-settings.ts`

### Geometry and Interaction

- [Path geometry](https://github.com/fefedu973/lumathread/blob/main/src/runtime/geometry-controller.ts): `src/runtime/geometry-controller.ts`
- [Path sampling](https://github.com/fefedu973/lumathread/blob/main/src/geometry/path-sampling.ts): `src/geometry/path-sampling.ts`
- [Motion propagation](https://github.com/fefedu973/lumathread/blob/main/src/geometry/propagation.ts): `src/geometry/propagation.ts`
- [Pointer following](https://github.com/fefedu973/lumathread/blob/main/src/runtime/follow-controller.ts): `src/runtime/follow-controller.ts`
- [Filament disturbance](https://github.com/fefedu973/lumathread/blob/main/src/interaction/filament-disturbance.ts): `src/interaction/filament-disturbance.ts`

### WebGL Rendering

- [Renderer runtime](https://github.com/fefedu973/lumathread/blob/main/src/runtime/HdrHeroWaveBackground.tsx): `src/runtime/HdrHeroWaveBackground.tsx`
- [Draw orchestration](https://github.com/fefedu973/lumathread/blob/main/src/runtime/draw-controller.ts): `src/runtime/draw-controller.ts`
- [Path renderer](https://github.com/fefedu973/lumathread/blob/main/src/runtime/path-renderer.ts): `src/runtime/path-renderer.ts`
- [Sine renderer](https://github.com/fefedu973/lumathread/blob/main/src/runtime/sine-renderer.ts): `src/runtime/sine-renderer.ts`
- [Glass and terrain](https://github.com/fefedu973/lumathread/blob/main/src/runtime/glass-terrain-renderer.ts): `src/runtime/glass-terrain-renderer.ts`
- [GPU resources](https://github.com/fefedu973/lumathread/blob/main/src/runtime/resource-manager.ts): `src/runtime/resource-manager.ts`
- [WebGL programs](https://github.com/fefedu973/lumathread/blob/main/src/rendering/webgl-resources.ts): `src/rendering/webgl-resources.ts`
- [DOM glass tracking](https://github.com/fefedu973/lumathread/blob/main/src/runtime/use-glass-text-dom-target.ts): `src/runtime/use-glass-text-dom-target.ts`

### Showcase and Lab

- [Site entry](https://github.com/fefedu973/lumathread/blob/main/site/main.tsx): `site/main.tsx`
- [Homepage showcase](https://github.com/fefedu973/lumathread/blob/main/site/pages/home.tsx): `site/pages/home.tsx`
- [Live demos](https://github.com/fefedu973/lumathread/blob/main/site/components/demo/showcase.tsx): `site/components/demo/showcase.tsx`
- [Configuration lab](https://github.com/fefedu973/lumathread/blob/main/site/pages/lab.tsx): `site/pages/lab.tsx`
- [Lab controller](https://github.com/fefedu973/lumathread/blob/main/site/features/lab/use-lab-controller.ts): `site/features/lab/use-lab-controller.ts`
- [Lab state model](https://github.com/fefedu973/lumathread/blob/main/site/features/lab/model/initial-state.ts): `site/features/lab/model/initial-state.ts`
- [Interactive stage](https://github.com/fefedu973/lumathread/blob/main/site/features/lab/stage/lab-stage.tsx): `site/features/lab/stage/lab-stage.tsx`
- [Lab controls](https://github.com/fefedu973/lumathread/blob/main/site/features/lab/controls/lab-control-panel.tsx): `site/features/lab/controls/lab-control-panel.tsx`
- [API reference](https://github.com/fefedu973/lumathread/blob/main/site/data/api-reference.ts): `site/data/api-reference.ts`

### Other components

- **React developer**
- **Showcase visitor**

## Connections

- React developer → Public exports: imports
- Public exports → Component API: exports
- Component API → Settings resolution: resolves props
- Component API → Renderer runtime: renders
- Renderer runtime → Path geometry: updates paths
- Path geometry → Path sampling: samples paths
- Path geometry → Motion propagation: builds motion
- Renderer runtime → Pointer following: updates follow
- Path geometry → Filament disturbance: applies impulses
- Renderer runtime → Draw orchestration: draws frames
- Draw orchestration → Path renderer: dispatches paths
- Draw orchestration → Sine renderer: dispatches sine
- Draw orchestration → Glass and terrain: draws effects
- Path renderer → GPU resources: uses resources
- Sine renderer → GPU resources: uses resources
- Glass and terrain → GPU resources: uses resources
- GPU resources → WebGL programs: creates programs
- Renderer runtime → DOM glass tracking: tracks target
- Showcase visitor → Site entry: opens site
- Site entry → Homepage showcase: routes home
- Homepage showcase → Live demos: shows demos
- Homepage showcase → API reference: presents reference
- Showcase visitor → Configuration lab: opens lab
- Configuration lab → Lab controller: creates controller
- Lab controller → Lab state model: uses state
- Lab controller → Lab controls: provides controls
- Lab controller → Interactive stage: configures stage
- Interactive stage → Component API: renders preview