How hinarosha/breathdearmedusae works
Project type & purpose (what you’re diagramming)
This is a single-page frontend WebGL experience: a React 19 + Vite app that renders an “organic background particle engine” using Three.js via React Three Fiber (R3F) and custom GLSL shaders. There is no backend and no database in the provided tree—your “system” is primarily a browser runtime pipeline (React → R3F → Three/WebGL → GPU shaders), plus the build toolchain (Vite).
File tree analysis → infer real components
From the tree:
• Build/Tooling
• package.json, package-lock.json (dependencies/scripts)
• vite.config.js (bundler/dev server config)
• eslint.config.js (lint rules)
• index.html (app entry HTML; Vite mounts here)
• Runtime Application (React)
• src/main.jsx (React bootstrap; mounts app into DOM)
• src/App.jsx (root component; likely hosts the 3D canvas + any UI)
• src/App.css, src/index.css (styling)
• 3D/Engine-ish module(s)
• src/assets/medusae.jsx (key domain file; likely creates geometry/material/shader logic, instancing, uniforms, animation loop hooks)
• Static files
• public/ (static assets served as-is by Vite)
This suggests a clean split for diagramming:
What to look for in README and reflect
The README strongly implies these architectural “centers of gravity” that should appear explicitly:
• High-performance instanced rendering (so include “InstancedMesh / Instancing system” as a component)
• Reactive / weighted / alive movement (so show input signals like time, pointer/mouse, scroll, audio if any; at least “time/uniforms”)
Toolchain
• npm run dev → Vite Dev Server → Browser loads index.html + module graph
App bootstrap
• Browser loads index.html → runs src/main.jsx → renders App.jsx into DOM root
React → R3F boundary
• App.jsx → creates <Canvas> (R3F) → declarative scene graph
• React state/props → influence R3F components (e.g., uniforms, parameters)
R3F render loop
• R3F useFrame/render loop → updates uniforms/time → triggers WebGL render
• Resize observer / DPR changes → update camera/renderer sizes
Engine module
• App.jsx (or a Scene component) → imports assets/medusae.jsx
• medusae.jsx → constructs InstancedMesh + ShaderMaterial → registers frame updates
• Frame update → uniform updates (time, breathing amplitude, pointer influence)
Three/WebGL → GPU shaders
• Output → Canvas framebuffer → visible background
Important architectural patterns
• Declarative scene composition (React/R3F) over imperative WebGL
• Separation of concerns:
• UI/Composition: App.jsx
• Engine/Simulation: medusae.jsx
• Rendering: Three.js + shaders
• Performance strategy: GPU instancing + shader-driven motion (minimize CPU per-particle updates)
Relevant technologies
• React 19, Vite, R3F, Three.js, WebGL, GLSL
• Optional: ESLint (quality gate) in toolchain
Labels
• Use concrete names tied to the repo:
• “src/main.jsx (bootstrap)”
• “src/App.jsx (root UI + Canvas host)”
• “src/assets/medusae.jsx (instanced particle system + shader material)”
• “JS module import”
• “uniforms: time, amplitude, pointer”