# rdev/liquid-glass-react architecture

> Architecture diagram of the GitHub repository rdev/liquid-glass-react, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdev/liquid-glass-react
- Repository: https://github.com/rdev/liquid-glass-react

## Overview

##### Project type + purpose (what you’re diagramming)
This repo is primarily a **React UI component library** published as `liquid-glass-react`, implementing **Apple-like “Liquid Glass”** visuals using **shader/refraction-style rendering** (likely WebGL/canvas + fragment/vertex shader logic), exposed as a single main component (`LiquidGlass`) with many visual/interaction props.

Additionally, the repo contains a **full demo/consumer application** under `liquid-glass-example/`, implemented as a **Next.js app** to showcase the library.

So your “system” is not a classic backend system; it’s:
- a **library package** (build + runtime behavior in the browser), and
- an **example web app** that depends on it.

1) how the library works internally at runtime (browser rendering pipeline + interactions), and

##### README insights → key runtime concepts
From the README, the library’s important behaviors are:
- Refraction/displacement (“edgy bending and refraction”)
- Multiple modes: `"standard" | "polar" | "prominent" | "shader"`
- Blur/frosting, saturation, chromatic aberration
- Hover/click effects, elasticity (“liquid feel”)
- Mouse tracking possibly over:
- component itself, OR
- a larger `mouseContainer` ref, OR
- external/manual `globalMousePos`
- Browser support caveat: Safari/Firefox partial support (displacement not visible)

**Props → event/mouse tracking → computed effect parameters → shader uniforms → render output**.

##### Library Source (TypeScript/React)
- `src/index.tsx`
- `src/shader-utils.ts`
- `src/utils.ts`
##### Build/Bundling
- `esbuild.config.js`
- Outputs: `dist/` (not shown in tree but implied) as ESM/CJS + types
##### Deployment Targets
- **npm package artifact**
- **Next.js static/server deployment** (depending on config)

- Library Source → (built by) Build/Bundling → npm package artifact
- Example App → imports → npm package (or local workspace link)
- Example App → deployed to → demo hosting (the README demo URL)

- Blue: Source code containers
- Purple: Build pipeline
- Green: Runtime/deployment artifacts
- Gray: External systems (npm, browser, hosting)

**Goal:** Show how `LiquidGlass` works at runtime in the browser.

##### React Component: `LiquidGlass` (src/index.tsx)
- Inputs: props (displacementScale, blurAmount, saturation, elasticity, mode, etc.)
- Renders: wrapper DOM + possibly a canvas overlay + children content

##### Interaction Layer
- Pointer/mouse tracking:
- Source: `mouseContainer` ref OR component element OR `globalMousePos`
- Output: normalized mouse position / velocity
- Hover/click state machine:
- hover → highlight/refraction changes
- click → press effect / ripple-like distortion (if implemented)

##### Rendering/Shader Pipeline (src/shader-utils.ts)
- Initializes WebGL/canvas context
- Loads/compiles shaders (mode `"shader"` likely uses the most direct shader path)
- Updates uniforms each frame:
- displacementScale, blurAmount, saturation, aberrationIntensity
- mouse position, time, elasticity
- “overLight” toggles highlight/edge behavior
- Produces final composited visual output

##### Utilities (src/utils.ts)
- Math helpers, clamping, lerp/spring, RAF scheduling, event normalization, etc.

##### Browser APIs
- DOM (layout, styles)
- Pointer events
- requestAnimationFrame
- WebGL/Canvas rendering
- CSS filters/compositing (if used)

- Props → `LiquidGlass` → Interaction Layer (configures event sources)
- Mouse events/globalMousePos → Interaction Layer → “Effect State” (mouseX/Y, velocity)
- DOM measurements → Geometry/Layout → Shader uniforms
- Effect State + Geometry → Shader Pipeline → Canvas/WebGL output
- Canvas/WebGL output → visually overlays/underlays children content (compositing relationship)

**mode switching**:
- `mode` → selects shader program / algorithm branch:
- standard/polar/prominent/shader → different uniform sets or render paths

- Safari/Firefox partial support → displacement may not render (likely due to WebGL/texture/displacement technique constraints)

##### Labels for each component
Use file-backed names where possible:
- `src/index.tsx (LiquidGlass component)`
- `src/shader-utils.ts (WebGL/shader helpers)`
- `src/utils.ts (math/event helpers)`
- `esbuild.config.js (bundle pipeline)`
- `liquid-glass-example (Next.js demo)`

##### “Don’t overthink it” but be very detailed: how to maximize component separation here
- **Prop Parsing/Defaults**
- **Event Source Selector** (`mouseContainer` vs local vs `globalMousePos`)
- **Motion Model** (elasticity/smoothing)
- **Layout Resolver** (padding/cornerRadius)
- **Mode Router** (standard/polar/prominent/shader)
- **Shader Program Manager**
- **Uniform Updater**
- **RAF Scheduler**
- **Compositor** (how canvas/glass layer overlays children)

- `pages/index.tsx` (renders examples)
- styling pipeline (globals.css/postcss)
- Next runtime (client-side rendering + optional server aspects)

That combination will be the most accurate representation of this project’s real architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================================================
%% Level 1 — System Context
%% =========================================================
subgraph "Level 1 — System Context"
direction TB

Dev["Developer / Consumer"]:::external
DemoUsers["Demo Site Visitors"]:::external

NpmRegistry["npm Registry"]:::external
Browser["Browser Runtime\n(DOM • Pointer Events • RAF • Canvas/WebGL)"]:::external
Hosting["Demo Hosting\n(Vercel/Static/Node)"]:::external

Pkg["liquid-glass-react\n(React UI Component Library)"]:::library
Demo["liquid-glass-example\n(Next.js Demo App)"]:::demo

Dev -->|"npm_install"| NpmRegistry
NpmRegistry -->|"distributes"| Pkg
Dev -->|"imports_and_renders"| Pkg

Demo -->|"depends_on"| Pkg
DemoUsers -->|"visit"| Hosting
Hosting -->|"serves"| Demo

Pkg -->|"runs_in"| Browser
Demo -->|"runs_in"| Browser
end

%% =========================================================
%% Level 2 — Repo Containers (Build + Demo)
%% =========================================================
subgraph "Level 2 — Repository Containers"
direction TB

subgraph "Library Package (Top-level)"
direction TB
LibMeta["Package Metadata\n(package.json)"]:::meta
LibTS["TypeScript Config\n(tsconfig.json)"]:::meta
LibAssets["Repo Assets\n(images/media)"]:::assets

subgraph "Library Source (TypeScript/React)"
direction TB
Entry["Public API Entry\n(LiquidGlass export)"]:::library
ShaderUtils["Shader / WebGL Helpers\n(compile • programs • uniforms)"]:::library
SharedUtils["Shared Utilities\n(math • events • RAF helpers)"]:::library
end

Build["Build/Bundling Pipeline\n(esbuild)"]:::build
Dist["Package Artifacts\n(ESM/CJS • types)\n(dist/)"]:::artifact
end

subgraph "Demo App (Next.js)"
direction TB
DemoMeta["Demo Package Metadata\n(package.json)"]:::meta
DemoTS["Demo TypeScript Config\n(tsconfig.json)"]:::meta
NextCfg["Next.js Config\n(next.config.ts)"]:::build
PostCSS["PostCSS Config\n(postcss.config.mjs)"]:::build

subgraph "Pages / App Shell"
direction TB
PageIndex["Demo Page\n(examples gallery)"]:::demo
AppShell["_app.tsx\n(app wrapper)"]:::demo
DocShell["_document.tsx\n(HTML template)"]:::demo
ApiHello["API Route\n(/api/hello)\n(not core)"]:::demoMuted
end

Styles["Global Styles\n(globals.css)"]:::demo
PublicAssets["Static Assets\n(public/)"]:::assets
end

%% Build-time relationships (dashed)
Entry -.->|"bundled_by"| Build
ShaderUtils -.->|"bundled_by"| Build
SharedUtils -.->|"bundled_by"| Build
LibMeta -.->|"inputs"| Build
LibTS -.->|"typecheck"| Build
Build -.->|"outputs"| Dist

%% Consumption relationships
DemoMeta -->|"deps"| PageIndex
PageIndex -->|"imports"| Entry
PageIndex -->|"renders"| Pkg
AppShell -->|"wraps"| PageIndex
DocShell -->|"defines_document"| AppShell
Styles -->|"applied_to"| AppShell
PublicAssets -->|"served_by"| Demo
ApiHello -->|"optional_fetch"| PageIndex

NextCfg -.->|"configures_build"| Demo
PostCSS -.->|"builds_css"| Styles

Dist -.->|"published_as"| NpmRegistry
Demo -.->|"deploys_to"| Hosting
end

%% =========================================================
%% Level 3 — Library Runtime Component Diagram
%% =========================================================
subgraph "Level 3 — Library Runtime (in the Browser)"
direction TB

Props["Public Props\n(mode • displacementScale • blurAmount • saturation • aberration • elasticity • mouseContainer • globalMousePos • etc.)"]:::api

subgraph "LiquidGlass Component Runtime"
direction TB

LiquidGlass["LiquidGlass React Component"]:::library

PropDefaults["Prop Parsing + Defaults"]:::module
EventSelector["Event Source Selector\n(mouseContainer vs local vs globalMousePos)"]:::module
Interaction["Interaction Layer\n(pointer tracking • hover/click state)"]:::module
MotionModel["Motion Model\n(lerp/spring • velocity • elasticity)"]:::module
Layout["Geometry / Layout Resolver\n(DOMRect • DPR • cornerRadius • padding)"]:::module

ModeRouter["Mode Router\nstandard | polar | prominent | shader"]:::router

subgraph "Rendering / Shader Pipeline"
direction TB
Raf["RAF Scheduler\n(requestAnimationFrame loop)"]:::module
GLInit["Context Init\n(Canvas/WebGL)"]:::render
ProgramMgr["Shader Program Manager\n(load/compile/link)"]:::render
Uniforms["Uniform Updater\n(time • mouse • params)"]:::render
Draw["Draw / Render Pass\n(fragment/vertex shading)"]:::render
Compositor["Compositor\n(glass layer + children)\n(blend/overlay)"]:::render
end

Utils["Utilities\n(clamp • math • event normalization)"]:::module
end

Compat["Browser Compatibility Note\nSafari/Firefox: displacement may be partial/not visible"]:::note

%% Runtime flows (solid)
Props -->|"configures"| LiquidGlass
LiquidGlass -->|"applies"| PropDefaults
PropDefaults -->|"drives"| EventSelector
EventSelector -->|"subscribes"| Interaction
Interaction -->|"feeds"| MotionModel
LiquidGlass -->|"measures"| Layout

PropDefaults -->|"selects"| ModeRouter
ModeRouter -->|"selects_program_path"| ProgramMgr

Utils -->|"helpers_for"| Interaction
Utils -->|"helpers_for"| MotionModel
Utils -->|"helpers_for"| Layout
Utils -->|"helpers_for"| Uniforms

MotionModel -->|"effect_state"| Uniforms
Layout -->|"geometry_params"| Uniforms
ModeRouter -->|"mode_params"| Uniforms

Raf -->|"tick"| Uniforms
Uniforms -->|"update_uniforms"| Draw
GLInit -->|"creates_context"| ProgramMgr
ProgramMgr -->|"binds_program"| Draw
Draw -->|"renders_to_canvas"| Compositor
LiquidGlass -->|"renders_children"| Compositor

%% Optional/conditional (dotted)
Props -.->|"globalMousePos_override"| Interaction

%% External bindings
Interaction -->|"pointer_events"| Browser
Layout -->|"DOM_measurements"| Browser
Raf -->|"requestAnimationFrame"| Browser
GLInit -->|"Canvas/WebGL"| Browser
Compositor -->|"visual_output"| Browser

Compat --- Browser
end

%% =========================================================
%% Click Events (from component mapping)
%% =========================================================
click Entry "https://github.com/rdev/liquid-glass-react/blob/master/src/index.tsx"
click ShaderUtils "https://github.com/rdev/liquid-glass-react/blob/master/src/shader-utils.ts"
click SharedUtils "https://github.com/rdev/liquid-glass-react/blob/master/src/utils.ts"
click Build "https://github.com/rdev/liquid-glass-react/blob/master/esbuild.config.js"
click LibMeta "https://github.com/rdev/liquid-glass-react/blob/master/package.json"
click LibTS "https://github.com/rdev/liquid-glass-react/blob/master/tsconfig.json"
click LibAssets "https://github.com/rdev/liquid-glass-react/tree/master/assets/"
click Demo "https://github.com/rdev/liquid-glass-react/tree/master/liquid-glass-example/"
click PageIndex "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/src/pages/index.tsx"
click AppShell "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/src/pages/_app.tsx"
click DocShell "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/src/pages/_document.tsx"
click ApiHello "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/src/pages/api/hello.ts"
click Styles "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/src/styles/globals.css"
click PublicAssets "https://github.com/rdev/liquid-glass-react/tree/master/liquid-glass-example/public/"
click NextCfg "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/next.config.ts"
click PostCSS "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/postcss.config.mjs"
click DemoMeta "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/package.json"
click DemoTS "https://github.com/rdev/liquid-glass-react/blob/master/liquid-glass-example/tsconfig.json"

%% =========================================================
%% Styles
%% =========================================================
classDef external fill:#ECEFF4,stroke:#4C566A,stroke-width:1px,color:#2E3440
classDef library fill:#D6EAF8,stroke:#1F77B4,stroke-width:1.5px,color:#0B3D91
classDef demo fill:#D5F5E3,stroke:#1E8449,stroke-width:1.5px,color:#0B3B1E
classDef demoMuted fill:#EAFAF1,stroke:#7DCEA0,stroke-width:1px,color:#2D6A4F,stroke-dasharray: 4 3
classDef build fill:#E8DAEF,stroke:#7D3C98,stroke-width:1.5px,color:#3B1B5A
classDef artifact fill:#FDEBD0,stroke:#B9770E,stroke-width:1.5px,color:#5A3A00
classDef assets fill:#FEF9E7,stroke:#B7950B,stroke-width:1px,color:#5A4A00
classDef api fill:#D6EAF8,stroke:#1565C0,stroke-width:2px,color:#0B3D91
classDef module fill:#EAF2F8,stroke:#2E86C1,stroke-width:1px,color:#1B4F72
classDef render fill:#FADBD8,stroke:#C0392B,stroke-width:1.5px,color:#641E16
classDef router fill:#FCF3CF,stroke:#B7950B,stroke-width:1.5px,color:#5A4A00
classDef meta fill:#F4F6F7,stroke:#566573,stroke-width:1px,color:#2C3E50
classDef note fill:#FFF3CD,stroke:#B08B00,stroke-width:1px,color:#5A4A00
```
