# captainalready/thematrix3dportfolio architecture

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

- Interactive diagram: https://gitdiagram.com/captainalready/thematrix3dportfolio
- Repository: https://github.com/captainalready/thematrix3dportfolio

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Runtime Architecture
%% =========================
subgraph "Runtime (Browser)"
direction TB

U["User"]:::external

subgraph "User Browser"
direction TB
DOM["DOM + CSS Rendering"]:::browser
React["React Runtime (SPA)"]:::frontend
App["App Composition (Root UI)"]:::frontend
LoadUI["Loading / Progress UI"]:::frontend
Three["Three.js Rendering Subsystem"]:::three
Scene["Scene Setup + Render Loop"]:::three
Matrix["Matrix Visual / Effect Module"]:::three
Assets["Asset Loading Layer (GLTF + Audio)"]:::asset
GPU["WebGL Context / GPU"]:::browser
IFrame["Embedded iframe (2D Portfolio)"]:::external
end

U -->|"interacts_with"| DOM
DOM -->|"events"| React
React -->|"renders"| App
App -->|"toggles_loading_ui"| LoadUI
App -->|"initializes"| Three
Three -->|"configures"| Scene
Scene -->|"uses"| Matrix
Scene -->|"requests_assets"| Assets
Assets -->|"provides_meshes_audio"| Scene
Scene -->|"requestAnimationFrame_render_loop"| GPU
App -->|"renders_iframe_src"| IFrame
end

subgraph "Static Hosting (This App Deployment)"
direction TB
Host["Static Host / CDN (serves build artifacts)"]:::host
BuildRoot["Build Artifact Root"]:::host
BuildIndex["index.html (production)"]:::artifact
BuildStatic["static/ (bundled JS/CSS)"]:::artifact
BuildCSS["main.css bundle"]:::artifact
BuildManifest["asset-manifest.json"]:::artifact
BuildGLB1["matrixdesk-transformed.glb"]:::asset
BuildGLB2["matrixdesk-mobile-transformed.glb"]:::asset
BuildGLB3["Monitor-transformed.glb"]:::asset
BuildMP3["cityrain.mp3"]:::asset
end

subgraph "External System"
direction TB
ExtHost["External Web Host (Portfolio2D)"]:::external
ExtSite["2D Portfolio Site"]:::external
end

%% Runtime HTTP flows
DOM -->|"HTTP_GET_html_js_css_assets"| Host
Host -->|"serves"| BuildRoot
BuildRoot -->|"contains"| BuildIndex
BuildRoot -->|"contains"| BuildStatic
BuildStatic -->|"includes"| BuildCSS
BuildRoot -->|"maps_assets"| BuildManifest
BuildRoot -->|"serves"| BuildGLB1
BuildRoot -->|"serves"| BuildGLB2
BuildRoot -->|"serves"| BuildGLB3
BuildRoot -->|"serves"| BuildMP3

Assets -->|"fetch_GLTF_GLb"| BuildGLB1
Assets -->|"fetch_GLTF_GLb"| BuildGLB2
Assets -->|"fetch_GLTF_GLb"| BuildGLB3
Assets -->|"fetch_audio_mp3"| BuildMP3

IFrame -->|"navigates_to"| ExtHost
ExtHost -->|"serves"| ExtSite

%% =========================
%% Build / Deploy Pipeline
%% =========================
subgraph "Build & Deploy (Toolchain)"
direction TB

Dev["Developer Machine"]:::tool
NPM["Node.js + npm"]:::tool
Pkg["npm scripts + deps (package.json)"]:::tool
Lock["Dependency lockfile (package-lock.json)"]:::tool
WDS["Dev Server / Tooling (start)"]:::tool
WDSCompat["WDS5 compatibility setup"]:::tool
Src["src/ (React + Three.js code)"]:::code
Public["public/ (static assets + template)"]:::code
PubIndex["HTML template (mount point)"]:::code
Manifest["Web app manifest (PWA)"]:::code
PubGLB1["GLB (desktop)"]:::asset
PubGLB2["GLB (mobile)"]:::asset
PubGLB3["GLB (monitor)"]:::asset
PubMP3["MP3 (ambient audio)"]:::asset
BuildTool["Build Toolchain (bundle/compile)"]:::tool
BuildDir["/build output"]:::host
end

Dev -->|"npm_install"| NPM
NPM -->|"reads"| Pkg
NPM -->|"locks_versions"| Lock

Dev -->|"npm_run_start"| WDS
WDS -->|"runs"| WDSCompat
WDS -->|"serves_in_dev"| Src
WDS -->|"serves_in_dev"| Public

Dev -->|"npm_run_build"| BuildTool
BuildTool -->|"bundles"| Src
BuildTool -->|"copies_as_is"| Public
Public -->|"includes"| PubIndex
Public -->|"includes"| Manifest
Public -->|"includes"| PubGLB1
Public -->|"includes"| PubGLB2
Public -->|"includes"| PubGLB3
Public -->|"includes"| PubMP3

BuildTool -->|"produces"| BuildDir
BuildDir -.->|"deploy_upload"| Host

%% =========================
%% Click Events (from component_mapping)
%% =========================
click React "https://github.com/captainalready/thematrix3dportfolio/blob/main/src/index.js"
click App "https://github.com/captainalready/thematrix3dportfolio/blob/main/src/App.jsx"
click LoadUI "https://github.com/captainalready/thematrix3dportfolio/blob/main/src/LoadingScreen.jsx"
click Scene "https://github.com/captainalready/thematrix3dportfolio/blob/main/src/scene.jsx"
click Matrix "https://github.com/captainalready/thematrix3dportfolio/blob/main/src/matrix.jsx"
click DOM "https://github.com/captainalready/thematrix3dportfolio/blob/main/src/styles.css"

click PubIndex "https://github.com/captainalready/thematrix3dportfolio/blob/main/public/index.html"
click Manifest "https://github.com/captainalready/thematrix3dportfolio/blob/main/public/manifest.json"
click PubGLB1 "https://github.com/captainalready/thematrix3dportfolio/blob/main/public/matrixdesk-transformed.glb"
click PubGLB2 "https://github.com/captainalready/thematrix3dportfolio/blob/main/public/matrixdesk-mobile-transformed.glb"
click PubGLB3 "https://github.com/captainalready/thematrix3dportfolio/blob/main/public/Monitor-transformed.glb"
click PubMP3 "https://github.com/captainalready/thematrix3dportfolio/blob/main/public/cityrain.mp3"

click BuildRoot "https://github.com/captainalready/thematrix3dportfolio/tree/main/build/"
click BuildIndex "https://github.com/captainalready/thematrix3dportfolio/blob/main/build/index.html"
click BuildStatic "https://github.com/captainalready/thematrix3dportfolio/tree/main/build/static/"
click BuildCSS "https://github.com/captainalready/thematrix3dportfolio/blob/main/build/static/css/main.d25c3602.css"
click BuildManifest "https://github.com/captainalready/thematrix3dportfolio/blob/main/build/asset-manifest.json"
click BuildGLB1 "https://github.com/captainalready/thematrix3dportfolio/blob/main/build/matrixdesk-transformed.glb"
click BuildGLB2 "https://github.com/captainalready/thematrix3dportfolio/blob/main/build/matrixdesk-mobile-transformed.glb"
click BuildGLB3 "https://github.com/captainalready/thematrix3dportfolio/blob/main/build/Monitor-transformed.glb"
click BuildMP3 "https://github.com/captainalready/thematrix3dportfolio/blob/main/build/cityrain.mp3"

click WDS "https://github.com/captainalready/thematrix3dportfolio/blob/main/scripts/start.js"
click WDSCompat "https://github.com/captainalready/thematrix3dportfolio/blob/main/scripts/setupWds5Compat.js"
click Pkg "https://github.com/captainalready/thematrix3dportfolio/blob/main/package.json"
click Lock "https://github.com/captainalready/thematrix3dportfolio/blob/main/package-lock.json"

%% =========================
%% Styles
%% =========================
classDef browser fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0D47A1;
classDef frontend fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20;
classDef three fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px,color:#E65100;
classDef asset fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#4A148C;
classDef host fill:#E0F7FA,stroke:#00838F,stroke-width:1px,color:#004D40;
classDef artifact fill:#FAFAFA,stroke:#616161,stroke-width:1px,color:#212121;
classDef external fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#B71C1C;
classDef tool fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#F57F17;
classDef code fill:#ECEFF1,stroke:#455A64,stroke-width:1px,color:#263238;
```
