# collidingscopes/stark-shapes architecture

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

- Interactive diagram: https://gitdiagram.com/collidingscopes/stark-shapes
- Repository: https://github.com/collidingscopes/stark-shapes

## Overview

##### Project type and purpose
- It uses Three.js to render geometric patterns and MediaPipe for real-time hand-gesture controls.

##### File structure
- Top level:
– index.html: entry point
– main.js: application bootstrap, event wiring, and control logic
– geometry.js: definitions of 3D patterns (cube, sphere, helix, etc.)
– styles.css: basic site styling
– assets/: static images (e.g., OG image)
- No backend code—everything runs in the browser. No build tools or server-side components.

##### Extract insights from the README
- Live demo is hosted via GitHub Pages (static hosting).
- Core technologies: Three.js (renderer) and MediaPipe (hand-tracking library).
- Feature flows: pinch → zoom, rotate → orbit, clap → next pattern.

##### Main components
a. Static File Server (e.g., GitHub Pages)
b. Client (Browser)
– index.html (loads all JS/CSS)
– styles.css (UI layout)
– Three.js Renderer
– Scene & Camera Manager (main.js orchestrates)
– Geometry Module (geometry.js)
– Shader Module (chromatic-shader.js)
– Hand-Tracking Module (MediaPipe)
– UI Controller (gesture → camera/pattern events)
c. Device Resources
– Webcam (video feed)
d. External CDNs or libraries
– Three.js (via CDN)
– MediaPipe (via CDN)

##### Relationships & data flows
- Static File Server → serves index.html, JS, CSS, assets → Browser
- Browser → loads Three.js & MediaPipe libraries
- Browser ↔ Webcam: video frames → feed into MediaPipe
- MediaPipe → outputs hand-landmark events → UI Controller in main.js
- UI Controller → updates Scene & Camera parameters in Three.js Renderer
- Clap gesture → triggers Geometry Module to switch 3D pattern
- Renderer ↔ Shader Module: applies chromatic effects to meshes
- Renderer → draws frame → displayed to user

##### Architectural patterns & design principles
- Modularity: separate JS modules for geometry, shaders, and control logic.
- Data-flow pipeline: Webcam → Hand Tracking → Event Controller → Renderer.
- Static-site architecture: no server-side logic, all assets pre-built.

##### Detailed checklist
[ ] Show the index.html → JS/CSS load sequence
[ ] Indicate the webcam → MediaPipe → main.js event flow
[ ] Show main.js invoking geometry.js & chromatic-shader.js
[ ] Mark external CDNs (Three.js, MediaPipe)
[ ] Include the static hosting layer and assets folder

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Static Hosting" 
        direction TB
        SFS["GitHub Pages"]:::static
        ASSETS["assets/"]:::static
    end

    subgraph "Client (Browser)"
        direction TB
        HTML["index.html"]:::client
        CSS["styles.css"]:::client
        MainJS["main.js\n(Application Bootstrap & UI Controller)"]:::client
        subgraph "Modules"
            direction TB
            Renderer["Three.js Renderer"]:::client
            Geometry["Geometry Module\n(geometry.js)"]:::client
            Shader["Shader Module\n(chromatic-shader.js)"]:::client
            HandTrack["Hand-Tracking Module\n(MediaPipe)"]:::client
        end
    end

    subgraph "External Dependencies"
        direction TB
        ThreeJScdn["Three.js CDN"]:::external
        MediaPipcdn["MediaPipe CDN"]:::external
        Webcam["Webcam"]:::external
    end

    %% Hosting to Client
    SFS -->|serves| HTML
    SFS -->|serves| CSS
    SFS -->|serves| MainJS
    SFS -->|serves| Geometry
    SFS -->|serves| Shader
    SFS -->|serves| ASSETS

    %% HTML loads resources
    HTML -->|loads| CSS
    HTML -->|loads| MainJS
    HTML -->|pulls| ThreeJScdn
    HTML -->|pulls| MediaPipcdn

    %% Module interactions
    MainJS -->|initializes| Renderer
    MainJS -->|wires gestures| HandTrack
    MainJS -->|controls patterns| Geometry
    MainJS -->|applies shader| Shader
    HandTrack -->|landmark events| MainJS
    Renderer -->|renders| Shader

    %% External to Modules
    ThreeJScdn -->|provides API| Renderer
    MediaPipcdn -->|provides API| HandTrack
    Webcam -->|video frames| HandTrack

    %% Styles
    classDef client fill:#DEF,stroke:#036,stroke-width:1px
    classDef external fill:#DFD,stroke:#060,stroke-width:1px
    classDef static fill:#FED,stroke:#C60,stroke-width:1px

    %% Click events
    click HTML "https://github.com/collidingscopes/stark-shapes/blob/main/index.html"
    click MainJS "https://github.com/collidingscopes/stark-shapes/blob/main/main.js"
    click Geometry "https://github.com/collidingscopes/stark-shapes/blob/main/geometry.js"
    click Shader "https://github.com/collidingscopes/stark-shapes/blob/main/chromatic-shader.js"
    click CSS "https://github.com/collidingscopes/stark-shapes/blob/main/styles.css"
    click ASSETS "https://github.com/collidingscopes/stark-shapes/tree/main/assets/"
```
