# andrewwoan/woan-minecraft-folio architecture

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

- Interactive diagram: https://gitdiagram.com/andrewwoan/woan-minecraft-folio
- Repository: https://github.com/andrewwoan/woan-minecraft-folio

## Overview

##### Project type and purpose
- This is a single-page, front-end only “immersive three.js portfolio” built with React (JSX/SCSS), Vite, and Three.js.
- Purpose: deliver a 3D Minecraft-inspired interactive portfolio with audio, models, UI overlays, and modal interactions.

##### Key architectural components
A. Host & Build
- Vite dev server / build pipeline (vite.config.js, package.json scripts)
- Static file host (serves `public/` assets: audio, models, images, WASM)
B. Application Shell
- index.html → root `
`
- main.jsx → ReactDOM.render + global styles (index.scss)
C. UI Layer (React Components)
- Reusable UI components (`src/components/...`): Buttons, Info, Modal, LoadingScreen, AudioToggleButton, Project, About
- SCSS modules for styling
D. 3D Experience Layer
- Experience.jsx: sets up Three.js scene, renderer, camera, lighting
- Scene.jsx: mounts canvas, orchestrates model loading and update loop
- Model wrappers (`src/Experience/models/*.jsx`): load and place GLB assets in scene
E. State Management
- Stores (`src/Experience/stores`): audioStore (controls SFX/music), modalStore (open/close UI overlays)
- React hooks for subscribing to state changes
F. Asset Pipeline / Utilities
- wasm transcoder (`public/basis/basis_transcoder.wasm` + .js) for KTX2 texture decoding
- Helpers & hooks (`src/Experience/utils`): material conversion, GLTF loader wrapper, general utilities
- Global utilities (`src/utils/audioSystem.js`) for centralized audio playback

##### How components interact
- The browser loads index.html → main.jsx bootstraps React app.
- UI Layer and Experience Layer coexist:
- Experience sets up WebGL canvas and scene graph.
- UI Layer components overlay HTML controls that dispatch actions to stores.
- Stores mediate audio playback and modal visibility.
- Utility functions/hook abstract WebGL asset loading (GLTF + KTX2 via WASM) and material conversion.
- Vite bundles all JS/JSX/SCSS, copies public assets and WASM into final build.

##### Architectural patterns & principles
- Component-based UI (React)
- Separation of concerns: UI vs. 3D experience vs. state vs. assets
- Hook-based state management (lightweight custom stores, akin to Zustand)
- Asset loading pipeline abstracted via utility hooks
- WASM integration for texture transcoding

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Layer
    VITE["Vite Dev Server / Bundler"]:::frontend

    %% Static Assets Host
    STATIC["Static Assets<br>(models/, audio/, images/, WASM)"]:::assets

    %% Client Browser
    subgraph "Client (Browser)"
        direction TB
        subgraph "Application Shell"
            direction TB
            HTML["index.html"]:::frontend
            MAIN["src/main.jsx"]:::frontend
            SCSS["src/index.scss"]:::frontend
        end

        subgraph "React UI Components"
            direction TB
            UIComp["UI Components<br>(Button, Info, Modal, etc.)"]:::frontend
        end

        subgraph "3D Experience Layer"
            direction TB
            EXP["Experience.jsx<br>Scene.jsx"]:::frontend
            MODELS["Model Wrappers<br>(GLB Models)"]:::frontend
        end

        subgraph "State Management"
            direction TB
            STORES["audioStore, modalStore"]:::state
        end

        subgraph "Asset Loader & Utilities"
            direction TB
            UTIL["GLTF/WASM Utilities"]:::util
            WASM["WASM Basis Transcoder"]:::assets
        end
    end

    %% Connections
    VITE -->|"bundles code"| HTML
    VITE --> CLIENT
    STATIC -->|"serves assets"| UTIL
    UTIL -->|"loads textures/models"| EXP
    MODELS --> EXP
    EXP -->|"renders scene"| UIComp
    UIComp -->|"dispatch actions via Hooks API"| STORES
    STORES -->|"state updates"| UIComp
    STORES -->|"state updates"| EXP

    %% Click Events
    click VITE "https://github.com/andrewwoan/woan-minecraft-folio/blob/main/vite.config.js"
    click VITE "https://github.com/andrewwoan/woan-minecraft-folio/blob/main/package.json"
    click STATIC "https://github.com/andrewwoan/woan-minecraft-folio/tree/main/public/"
    click HTML "https://github.com/andrewwoan/woan-minecraft-folio/blob/main/index.html"
    click MAIN "https://github.com/andrewwoan/woan-minecraft-folio/blob/main/src/main.jsx"
    click SCSS "https://github.com/andrewwoan/woan-minecraft-folio/blob/main/src/index.scss"
    click UTIL "https://github.com/andrewwoan/woan-minecraft-folio/blob/main/src/Experience/utils/useGLTFWithKTX2.jsx"
    click WASM "https://github.com/andrewwoan/woan-minecraft-folio/blob/main/public/basis/basis_transcoder.wasm"

    %% Styles
    classDef frontend fill:#D5E8D4,stroke:#4CAF50,font-weight:bold
    classDef assets fill:#FFF2CC,stroke:#D6B656,font-weight:bold
    classDef state fill:#E1D5E7,stroke:#9673A6,font-weight:bold
    classDef util fill:#F8CECC,stroke:#B85450,font-weight:bold
```
