# jaxzin/lkg-blocks-viewer architecture

> Architecture diagram of the GitHub repository jaxzin/lkg-blocks-viewer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaxzin/lkg-blocks-viewer
- Repository: https://github.com/jaxzin/lkg-blocks-viewer

## Overview

##### Project type and purpose
- This is a client-side, single-page VR viewer built with React (JSX/TSX) and Vite. It is not a multi-tier full-stack service but a browser-based application that uses three.js for 3D/WebXR scenes. Its goal is to render “quilt” images in 3D space, handle VR controller interactions, and integrate with the Blocks Auth system so users can “play with Blocks like trading cards.”

##### File structure
- Top-level directories:
- build/ – output for production (assets, HTML, compiled JS)
- public/ – static assets served as-is (including XRScene.js, script.js)
- src/ – application source code
- Within src/:
- app.jsx, index.jsx – entrypoints
- components/ – React UI components (BlockCard, LoginButton, QuiltMaterial, etc.)
- pages/ – routed pages (home, about, block-test, xr-test)
- hooks/ – custom React hooks (useBlocksAuth, XR wiggle, reduced-motion)
- lib/ – standalone libraries (blocksAuthClient)
- styles/ – CSS files
- Configuration: vite.config.js for bundling; package.json for dependencies; shrinkwrap.yaml/package-lock.json for lockfiles.

##### README for additional insights
- Goals:
1. Custom shader for quilt images
2. WebXR controller integration
3. Blocks trading-card interactions
- Tech stack: three.js, React, Vite, WebXR API, custom shaders, BlocksAuth (likely calls external Blocks wallet service).

##### Main components and their interactions
a. Browser & User
- User operates in a WebXR-capable browser.
b. React SPA (app.jsx → router.tsx → pages + components)
- Renders UI and bootstraps three.js scene.
c. three.js Renderer & Scene Graph
- Hosts QuiltMaterial shader; updates per XR frame.
d. WebXR Device API
- Feeds VR headset/controller input to three.js.
e. BlocksAuth Client
- useBlocksAuth hook → lib/blocksAuthClient.ts → external Blocks API (authentication, user data).
f. Static Assets & Quilt Textures
- mesh geometry, quilt images served from public/ or build/assets.

##### Architectural patterns & design principles
- Component-based UI (React).
- SPA routing (Router TSX).
- Separation of concerns:
- UI layer (components)
- Rendering layer (three.js + custom shader)
- Auth/data layer (BlocksAuth client)
- Build pipeline (Vite): dev vs. prod (build/ folder).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer
    UserVR["User / VR Device"]:::external
    Browser["Browser"]:::external
    WebXRAPI["WebXR API"]:::rendering

    UserVR -->|"interacts via VR"| Browser
    Browser -->|"provides WebXR context"| WebXRAPI

    %% Application Layer
    subgraph "React Application" 
        direction TB
        subgraph "Entrypoints"
            direction TB
            Index["src/index.jsx"]:::ui
            App["src/app.jsx"]:::ui
        end
        subgraph "Routing"
            Router["src/components/router.tsx"]:::ui
        end
        subgraph "Pages"
            direction TB
            Home["src/pages/home.jsx"]:::ui
            About["src/pages/about.jsx"]:::ui
            BlockTest["src/pages/block-test.tsx"]:::ui
            XRTest["src/pages/xr-test.tsx"]:::ui
        end
        subgraph "Components"
            direction TB
            BlockCard["src/components/BlockCard.jsx"]:::ui
            BlockCard2["src/components/BlockCard2.js"]:::ui
            CardPreview["src/components/CardPreviewControls.tsx"]:::ui
            LoginButton["src/components/LoginButton.tsx"]:::auth
            SEO["src/components/seo.jsx"]:::ui
            RoundedRect["src/components/RoundedRect.js"]:::ui
        end
        subgraph "Hooks & Lib"
            direction TB
            UseAuth["src/hooks/useBlocksAuth.ts"]:::auth
            AuthClient["src/lib/blocksAuthClient.ts"]:::auth
            Wiggle["src/hooks/wiggle.jsx"]:::ui
            ReducedMotion["src/hooks/prefers-reduced-motion.jsx"]:::ui
        end
        Styles["src/styles/styles.css"]:::assets
    end

    Browser -->|"loads SPA"| Index
    Index --> App
    App --> Router
    Router --> Home
    Router --> About
    Router --> BlockTest
    Router --> XRTest

    Home --> BlockCard
    Home --> BlockCard2
    BlockCard --> CardPreview
    BlockCard2 --> CardPreview
    Home --> SEO

    App --> UseAuth
    UseAuth --> AuthClient
    AuthClient --> ExternalBlocksAPI
    ExternalBlocksAPI --> AuthClient
    AuthClient --> UseAuth
    UseAuth --> LoginButton
    LoginButton --> App

    %% Rendering Layer
    subgraph "Rendering"
        direction TB
        Renderer["three.js Renderer & Scene"]:::rendering
        Shader["src/components/QuiltMaterial.js"]:::rendering
        StaticAssets["public/js/XRScene.js\npublic/js/script.js\nbuild/assets/"]:::assets
    end

    WebXRAPI -->|"frame loop/events"| Renderer
    App -->|"passes geometry/textures"| Renderer
    Renderer --> Shader
    Renderer --> StaticAssets

    %% External
    ExternalBlocksAPI["External Blocks Auth API"]:::external

    %% Build Pipeline
    subgraph "Build Pipeline"
        direction TB
        Vite["vite.config.js"]:::tool
        BuildOut["build/"]:::assets
    end
    App -->|"bundles via Vite"| BuildOut
    Vite --> BuildOut

    %% Styling and Classes
    classDef ui fill:#ccf,stroke:#36c,stroke-width:1px
    classDef rendering fill:#cfc,stroke:#2a2,stroke-width:1px
    classDef auth fill:#fcf,stroke:#c36,stroke-width:1px
    classDef assets fill:#eee,stroke:#999,stroke-width:1px
    classDef external fill:#fdd,stroke:#d22,stroke-width:1px,stroke-dasharray: 5 5
    classDef tool fill:#ffd,stroke:#da0,stroke-width:1px,stroke-dasharray: 2 2

    %% Click Events
    click Index "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/index.jsx"
    click App "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/app.jsx"
    click Router "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/router.tsx"
    click Home "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/pages/home.jsx"
    click About "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/pages/about.jsx"
    click BlockTest "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/pages/block-test.tsx"
    click XRTest "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/pages/xr-test.tsx"
    click BlockCard "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/BlockCard.jsx"
    click BlockCard2 "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/BlockCard2.js"
    click CardPreview "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/CardPreviewControls.tsx"
    click LoginButton "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/LoginButton.tsx"
    click SEO "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/seo.jsx"
    click RoundedRect "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/RoundedRect.js"
    click Shader "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/components/QuiltMaterial.js"
    click AuthClient "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/lib/blocksAuthClient.ts"
    click UseAuth "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/hooks/useBlocksAuth.ts"
    click Wiggle "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/hooks/wiggle.jsx"
    click ReducedMotion "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/hooks/prefers-reduced-motion.jsx"
    click Styles "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/src/styles/styles.css"
    click Vite "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/vite.config.js"
    click StaticAssets "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/public/js/XRScene.js"
    click StaticAssets "https://github.com/jaxzin/lkg-blocks-viewer/blob/main/public/js/script.js"
    click BuildOut "https://github.com/jaxzin/lkg-blocks-viewer/tree/main/build/assets/"
```
