# dkoncius/banzai-box architecture

> Architecture diagram of the GitHub repository dkoncius/banzai-box, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dkoncius/banzai-box
- Repository: https://github.com/dkoncius/banzai-box

## Overview

##### Project Type and Purpose
- This is a front-end, single-page interactive 3D web application. Its sole purpose is to load and animate a Bonsai tree model in response to scroll events, using Three.js for rendering and GSAP (ScrollTrigger) for animation sequencing.
- There is no backend or data-persistence layer—everything runs in the browser, served by Vite during development or as static assets in production.

##### File-Structure Analysis
- Top level:
- index.html – entry point
- package.json / vite.config.js – build & dev-server config
- public/models/old_tree.glb – 3D asset
- src/:
- main.jsx – application bootstrap (mount React App)
- App.jsx – root React component
- components/ – React components, each encapsulating a piece of the animation or UI
- shaders/ – custom GLSL/JS shader materials for glow, hologram, pattern, tree surface
- styles/ – global CSS
- No “api” or “backend” folder—this is pure front-end.

##### README Insights
- Confirms 3D model loading (bonesai.glb), scroll-driven stages (Introduction, Growth, Seasonal Changes, Harmony, Full Bloom).
- Lists tech stack: Three.js, GSAP+ScrollTrigger, Vite.

##### Main Architectural Components
A. Browser / Client
– Renders the scene and UI
– Responds to user scroll events
B. Vite Dev Server / Static Server
– Serves index.html, JavaScript bundles, and public assets
C. React Application
– App.jsx orchestrates subcomponents
– Components:
- BanzaiTree – sets up Three.js Scene, Camera, Renderer, loads GLB
- TreeControls – GUI or scroll-linked controls
- CollaborativeStructure & NameShapeGenerator – additional scene elements or overlays
– main.jsx mounts App to DOM
D. Three.js Scene Graph
– Scene, Camera, WebGLRenderer
– Shaders as custom materials (GlowShaderMaterial.js, etc.)
E. GSAP + ScrollTrigger
– Listens for scroll positions
– Drives animations on Three.js mesh transforms, material parameters, camera positions
F. Static Assets
– public/models/*.glb
– CSS under src/styles

##### Relationships & Data Flows
1. Browser requests index.html → Vite serves compiled JS/CSS
2. main.jsx initializes React → App.jsx
3. App renders BanzaiTree → Three.js scene is created
4. GSAP ScrollTrigger hooks into window scroll → issues animation callbacks
6. Render loop (requestAnimationFrame) updates canvas

##### Architectural Patterns & Design Principles
- Component Isolation: each React component manages its own portion of the scene
- Separation of Concerns: shaders in their own folder, animation logic via GSAP, rendering via Three.js
- Declarative UI: React for DOM/CANVAS mounting, GSAP for imperative animations
- Asset Decoupling: public folder used for large binary assets, loaded at runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Server Layer
    subgraph "Vite Dev / Static Server"
        direction TB
        ViteConfig["vite.config.js"]:::client
        IndexHTML["index.html"]:::client
        PackageJSON["package.json"]:::client
    end

    %% Browser Client
    Browser["Browser / Client"]:::client

    %% React Application
    subgraph "React Application"
        direction TB
        Main["src/main.jsx"]:::client
        AppComp["src/App.jsx"]:::client
        subgraph "Components"
            direction TB
            BanzaiTree["BanzaiTree.jsx"]:::client
            TreeControls["TreeControls.jsx"]:::client
            CollaborativeStructure["CollaborativeStructure.jsx"]:::client
            NameShapeGen["NameShapeGenerator.jsx"]:::client
        end
        subgraph "Shaders"
            direction TB
            GlowShader["GlowShaderMaterial.js"]:::client
            HologramShader["HologramShaderMaterial.js"]:::client
            PatternShader["PatternShaderMaterial.js"]:::client
            TreeShader["TreeShaderMaterial.js"]:::client
        end
        Styles["src/styles/index.css"]:::client
    end

    %% Libraries
    ThreeJS["Three.js"]:::lib
    GSAP["GSAP / ScrollTrigger"]:::lib

    %% Static Asset Store
    Asset[(old_tree.glb)]:::asset

    %% Relationships
    Browser -->|requests entrypoint| IndexHTML
    Browser -->|scroll event| GSAP
    IndexHTML -->|serves bundle| Main
    Main -->|mounts| AppComp
    AppComp -->|includes| BanzaiTree
    AppComp -->|includes| TreeControls
    AppComp -->|includes| CollaborativeStructure
    AppComp -->|includes| NameShapeGen
    BanzaiTree -->|uses| ThreeJS
    BanzaiTree -->|loads model| Asset
    BanzaiTree -->|uses shaders| GlowShader
    BanzaiTree -->|uses shaders| HologramShader
    BanzaiTree -->|uses shaders| PatternShader
    BanzaiTree -->|uses shaders| TreeShader
    TreeControls -->|controls| BanzaiTree
    GSAP -->|animation callbacks| BanzaiTree
    BanzaiTree -->|renders to canvas| Browser
    Styles -->|global CSS| AppComp

    %% Click Events
    click ViteConfig "https://github.com/dkoncius/banzai-box/blob/main/vite.config.js"
    click IndexHTML "https://github.com/dkoncius/banzai-box/blob/main/index.html"
    click PackageJSON "https://github.com/dkoncius/banzai-box/blob/main/package.json"
    click Main "https://github.com/dkoncius/banzai-box/blob/main/src/main.jsx"
    click AppComp "https://github.com/dkoncius/banzai-box/blob/main/src/App.jsx"
    click BanzaiTree "https://github.com/dkoncius/banzai-box/blob/main/src/components/BanzaiTree.jsx"
    click TreeControls "https://github.com/dkoncius/banzai-box/blob/main/src/components/TreeControls.jsx"
    click CollaborativeStructure "https://github.com/dkoncius/banzai-box/blob/main/src/components/CollaborativeStructure.jsx"
    click NameShapeGen "https://github.com/dkoncius/banzai-box/blob/main/src/components/NameShapeGenerator.jsx"
    click GlowShader "https://github.com/dkoncius/banzai-box/blob/main/src/shaders/GlowShaderMaterial.js"
    click HologramShader "https://github.com/dkoncius/banzai-box/blob/main/src/shaders/HologramShaderMaterial.js"
    click PatternShader "https://github.com/dkoncius/banzai-box/blob/main/src/shaders/PatternShaderMaterial.js"
    click TreeShader "https://github.com/dkoncius/banzai-box/blob/main/src/shaders/TreeShaderMaterial.js"
    click Styles "https://github.com/dkoncius/banzai-box/blob/main/src/styles/index.css"
    click Asset "https://github.com/dkoncius/banzai-box/blob/main/public/models/old_tree.glb"

    %% Styles
    classDef client fill:#e0f2f1,stroke:#00695c,color:#004d40
    classDef lib fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    classDef asset fill:#fafafa,stroke:#9e9e9e,color:#616161
    classDef server fill:#eceff1,stroke:#455a64,color:#263238
```
