How dkoncius/banzai-box works
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