How captainalready/thematrix3dportfolio works
Project type & purpose (what you’re diagramming)
This is a client-side, static React SPA that renders an interactive 3D scene in the browser using Three.js/WebGL, styled with CSS, and it embeds a second “2D portfolio” site via an internal iframe (pointing to an external URL/repo).
There is no backend service and no database indicated by the tree/README. The “system” is primarily:
• Build-time toolchain (Node/npm + bundler) → produces /build
• Runtime in the browser (React + Three.js + asset loading + iframe)
File structure clues (how to split components)
Top-level:
• src/ → runtime application code
• App.jsx → main composition/root UI + likely mounts the 3D canvas and iframe container
• scene.jsx → Three.js scene setup (camera, lights, renderer, animation loop)
• matrix.jsx → likely custom Three.js effect/material/animation logic for “Matrix” visuals
• LoadingScreen.jsx → loading state while models/audio load
• index.js → React bootstrap
• styles.css → global styles
• public/ → static assets copied as-is (GLB models, MP3, HTML template, manifest)
• build/ → production output (already built) including bundled JS/CSS + copied assets
• scripts/ → dev server compatibility and start script (suggests CRA-like dev server customization)
Assets present:
• *.glb (3D models): matrixdesk-transformed.glb, matrixdesk-mobile-transformed.glb, Monitor-transformed.glb
• cityrain.mp3 (ambient audio)
You want to separate runtime components, external dependencies, and build/deploy components.
User Browser
• Renders DOM/CSS
• Provides WebGL context (GPU) for Three.js
• Loads static assets over HTTP(S)
React Application (SPA)
• Entry: src/index.js → mounts React root into public/index.html
• Root composition: src/App.jsx
• UI states: LoadingScreen.jsx (model/audio loading progress)
Three.js Rendering Subsystem
• Scene initialization/config: src/scene.jsx
• THREE.Scene
• Camera
• Renderer (WebGLRenderer)
• Animation loop (requestAnimationFrame)
• “Matrix” visual/effect module: src/matrix.jsx (treat as an internal subsystem feeding scene objects/materials/textures or postprocessing)
Asset Loading Layer
• GLB models loaded at runtime (from /public or bundled build path)
• likely via GLTFLoader
• Audio loaded/played (MP3)
• This is the key data-flow driver for the LoadingScreen.
Embedded 2D Portfolio (External)
• The app embeds an iframe pointing to Portfolio2D (external hosted site / separate deployment).
External “services” / boundaries (even if minimal)
• Static Hosting / CDN serving the built files (/build) + assets (GLB/MP3)
• External site hosting for the iframe target (Portfolio2D)
• Developer machine
• Node.js + npm
• Bundler/build toolchain (implied by React structure and scripts/)
• Outputs:
• /build/static/js, /build/static/css, asset-manifest.json, index.html
• Deploy step:
• Upload /build to static host/CDN
Browser → Static Host
• GET /index.html
• GET /static/js/* (React bundle)
• GET /static/css/*
• GET /*.glb, GET /cityrain.mp3
React App → Three.js subsystem
• App.jsx instantiates/owns the canvas container (or a component) and triggers scene init.
• React state drives showing LoadingScreen until loaders resolve.
Three.js subsystem → Asset Loading
• scene.jsx requests GLB via loader(s)
• on load completion → adds meshes to THREE.Scene
• audio load → play/loop ambient sound
Three.js subsystem → Browser GPU/WebGL
• WebGLRenderer draws frames via requestAnimationFrame
React App → iframe (External 2D Portfolio)
• App renders <iframe src="...">
• Browser loads iframe document from separate origin/host
• (Optional note) sandboxing/cross-origin restrictions; limited integration unless postMessage is used (not indicated here).
Architectural patterns/design principles to highlight
• Component-based UI composition (React)
• Subsystem encapsulation: React UI vs Three.js scene (imperative render loop)
• Asynchronous asset pipeline (GLB/audio) + loading state management (LoadingScreen)
• Static-site deployment (no server-side runtime)
• Multi-app composition via iframe (loose coupling; independent deploy cycles)
• React root: src/index.js, src/App.jsx
• Loading state: src/LoadingScreen.jsx
• 3D engine module(s): src/scene.jsx, src/matrix.jsx
• Static assets: public/*.glb, public/cityrain.mp3
• Build output: build/index.html, build/static/css/*, build/asset-manifest.json
• Dev/start tooling: scripts/start.js, scripts/setupWds5Compat.js
9) “Don’t overthink it” decomposition checklist (include as many meaningful components as possible)
For this repo, “more components” that are still real and useful:
• “Model Loader (GLTFLoader)” subcomponent within Three.js
• “Audio Controller” subcomponent for ambient loop
• “Device/Viewport switch” (because there are desktop/mobile GLBs)
• “Loading/Progress UI”
• “Animation Loop / Tick”