# hinarosha/breathdearmedusae architecture

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

- Interactive diagram: https://gitdiagram.com/hinarosha/breathdearmedusae
- Repository: https://github.com/hinarosha/breathdearmedusae

## Overview

##### 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”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Build & Delivery (Tooling)
  %% =========================
  subgraph "Build & Delivery (Local Dev / Prod Build)"
    Dev["Developer"]:::external

    subgraph "Node Tooling"
      NPM["npm scripts<br/>(dev/build/lint)"]:::tooling
      PKG["package.json<br/>(deps & scripts)"]:::file
      LOCK["package-lock.json<br/>(pinned deps)"]:::file
      ESLINT["ESLint Config"]:::tooling
      ESLINTCFG["eslint.config.js"]:::file
    end

    subgraph "Vite"
      VITE["Vite (Dev Server / Bundler)"]:::tooling
      VITECFG["vite.config.js"]:::file
      DIST["Static Bundle Output<br/>(JS/CSS/Assets)"]:::artifact
    end

    README["README.md<br/>(Architecture Notes)"]:::doc
  end

  %% =========================
  %% Browser Runtime (SPA)
  %% =========================
  subgraph "Browser Runtime (Single-Page App)"
    USER["User"]:::external
    BROWSER["Browser"]:::external

    HTML["index.html<br/>(mount point)"]:::file
    DOM["DOM Root<br/>(#root)"]:::runtime

    subgraph "React App (React 19)"
      MAIN["React Bootstrap<br/>(src/main.jsx)"]:::runtime
      APP["Root Component<br/>(src/App.jsx)"]:::runtime
      APP_CSS["App Styles<br/>(src/App.css)"]:::file
      INDEX_CSS["Global Styles<br/>(src/index.css)"]:::file
    end

    subgraph "3D Rendering Stack"
      R3F["React Three Fiber (R3F)<br/><Canvas> + useFrame loop"]:::render
      THREE["Three.js Core<br/>(Scene/Camera/WebGLRenderer)"]:::render
      CANVAS["HTML Canvas<br/>(WebGL drawing surface)"]:::runtime
    end

    subgraph "Engine Module (Domain Logic)"
      MEDUSAE["Medusa / Particle Engine<br/>(instancing + shader material)"]:::engine
      INST["Instanced Rendering<br/>(InstancedMesh / instance attrs)"]:::engine
      UNIF["Uniforms & Params<br/>(time, amplitude, pointer, DPR/resize)"]:::engine
      SHMAT["ShaderMaterial Setup"]:::engine
    end

    subgraph "GPU Pipeline (WebGL/GLSL)"
      WEBGL["WebGL API / Driver"]:::gpu
      VERT["GLSL Vertex Shader<br/>(motion + instance transforms)"]:::gpu
      FRAG["GLSL Fragment Shader<br/>(color/gradient)"]:::gpu
      FB["Framebuffer Output<br/>(final pixels)"]:::gpu
    end

    subgraph "Assets"
      PUBLIC["public/ (static assets)"]:::asset
      ASSETSDIR["src/assets/ (code-based assets)"]:::asset
    end

    INPUTS["Runtime Inputs<br/>(pointer/touch, resize, time)"]:::external
  end

  %% =========================
  %% Build-time flows (dashed)
  %% =========================
  Dev -.->|"edit & run"| NPM
  NPM -.->|"reads"| PKG
  NPM -.->|"uses"| LOCK
  NPM -.->|"lint"| ESLINT
  ESLINT -.->|"rules from"| ESLINTCFG

  NPM -.->|"dev/build"| VITE
  VITE -.->|"config"| VITECFG
  VITE -.->|"serves/bundles"| HTML
  VITE -.->|"builds"| DIST
  README -.->|"documents"| APP

  %% =========================
  %% Runtime flows (solid)
  %% =========================
  USER -->|"interacts"| BROWSER
  BROWSER -->|"loads"| HTML
  HTML -->|"mounts into"| DOM
  HTML -->|"loads modules"| MAIN
  MAIN -->|"renders"| APP

  APP -->|"applies"| APP_CSS
  APP -->|"applies"| INDEX_CSS

  APP -->|"creates"| R3F
  R3F -->|"drives scene graph"| THREE
  THREE -->|"renders to"| CANVAS

  %% Engine composition
  APP -->|"imports"| MEDUSAE
  ASSETSDIR -->|"contains"| MEDUSAE
  MEDUSAE -->|"sets up"| INST
  MEDUSAE -->|"updates"| UNIF
  MEDUSAE -->|"creates"| SHMAT
  SHMAT -->|"uses"| VERT
  SHMAT -->|"uses"| FRAG

  %% Render loop + uniforms
  INPUTS -->|"events"| R3F
  R3F -->|"per-frame (useFrame)"| UNIF
  UNIF -->|"bind uniforms"| SHMAT

  %% GPU execution pipeline
  THREE -->|"instanced draw calls"| WEBGL
  WEBGL -->|"executes"| VERT
  VERT -->|"rasterize"| FRAG
  FRAG -->|"writes"| FB
  FB -->|"present"| CANVAS

  %% Assets flow
  PUBLIC -->|"served as-is"| BROWSER
  VITE -.->|"serves"| PUBLIC

  %% =========================
  %% Click events (from mapping)
  %% =========================
  click PKG "https://github.com/hinarosha/breathdearmedusae/blob/main/package.json"
  click LOCK "https://github.com/hinarosha/breathdearmedusae/blob/main/package-lock.json"
  click VITECFG "https://github.com/hinarosha/breathdearmedusae/blob/main/vite.config.js"
  click ESLINTCFG "https://github.com/hinarosha/breathdearmedusae/blob/main/eslint.config.js"
  click HTML "https://github.com/hinarosha/breathdearmedusae/blob/main/index.html"
  click MAIN "https://github.com/hinarosha/breathdearmedusae/blob/main/src/main.jsx"
  click APP "https://github.com/hinarosha/breathdearmedusae/blob/main/src/App.jsx"
  click APP_CSS "https://github.com/hinarosha/breathdearmedusae/blob/main/src/App.css"
  click INDEX_CSS "https://github.com/hinarosha/breathdearmedusae/blob/main/src/index.css"
  click MEDUSAE "https://github.com/hinarosha/breathdearmedusae/blob/main/src/assets/medusae.jsx"
  click PUBLIC "https://github.com/hinarosha/breathdearmedusae/tree/main/public/"
  click ASSETSDIR "https://github.com/hinarosha/breathdearmedusae/tree/main/src/assets/"
  click README "https://github.com/hinarosha/breathdearmedusae/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ffffff,stroke:#374151,stroke-width:1.5,color:#111827
  classDef tooling fill:#e5e7eb,stroke:#6b7280,stroke-width:1.5,color:#111827
  classDef artifact fill:#f3f4f6,stroke:#6b7280,stroke-width:1.5,color:#111827
  classDef doc fill:#eef2ff,stroke:#4338ca,stroke-width:1.5,color:#111827

  classDef runtime fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5,color:#111827
  classDef render fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5,color:#111827
  classDef engine fill:#bfdbfe,stroke:#1e40af,stroke-width:1.5,color:#111827

  classDef gpu fill:#ffedd5,stroke:#c2410c,stroke-width:1.5,color:#111827
  classDef asset fill:#dcfce7,stroke:#166534,stroke-width:1.5,color:#111827
  classDef file fill:#f8fafc,stroke:#334155,stroke-width:1.2,color:#111827,stroke-dasharray: 3 3
```
