# danielrobertdinu/the-force architecture

> Architecture diagram of the GitHub repository danielrobertdinu/the-force, 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/danielrobertdinu/the-force
- Repository: https://github.com/danielrobertdinu/the-force

## Overview

##### Project type and purpose
- This is a front-end, single-page WebGL demo application.
- Its goal is to render and control a 3D particle animation in real time using hand-tracking gestures via the user’s webcam.

##### File structure analysis
- Top-level files only:
- index.html – the entry point, includes the HTML skeleton and script/style references
- main.js – the core orchestration code: loads Three.js, sets up the scene, runs the render loop, hooks into MediaPipe
- styles.css – any CSS styles for canvas/UI layout
- No backend or build scripts: everything runs in the browser.
- External dependencies are loaded at runtime (Three.js, MediaPipe).

##### README insights
- Confirms use of Three.js for 3D rendering, MediaPipe for hand-tracking, HTML5 Canvas for the viewport, JavaScript for glue logic.
- No server-side component; it’s purely client-side.

1. Browser environment
2. User’s Webcam (video feed)
3. MediaPipe Hand-Tracking pipeline
4. JavaScript orchestration layer (main.js)
5. Three.js Renderer + WebGL Context
6. HTML5 Canvas element (display viewport)
7. 3D Particle System (Three.js Scene + GPU shaders)
b. Relationships & interactions
- Browser grants camera access → Video feed flows into MediaPipe
- MediaPipe outputs hand landmarks → fed to main.js
- main.js uses landmarks to update Three.js scene parameters (e.g., particle emitter position, force vectors)
- Three.js Renderer draws the updated scene onto the Canvas each animation frame
c. Architectural patterns & design principles
- Event-driven, real-time rendering loop: requestAnimationFrame loop in main.js
- Separation of concerns:
- Media pipeline (MediaPipe)
- Rendering engine (Three.js/WebGL)
- Application logic (main.js)
- Single-responsibility modules: each library handles its domain
d. Key technologies to annotate
- Browser Web APIs: getUserMedia, requestAnimationFrame
- MediaPipe Hands (WebAssembly/C++ under the hood)
- Three.js (JavaScript library atop WebGL)
- HTML5 Canvas (with WebGL context)
- CSS for layout

##### Essential details
- Real-time loop (requestAnimationFrame → render → update → repeat).
- How hand landmarks map to 3D forces in the particle system.
- Minimal file-level context: index.html loads scripts/styles, main.js drives everything.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware
    Webcam["User Webcam"]:::hardware
    Webcam -->|Video Feed|getUserMedia["getUserMedia Pipeline"]:::htmlcss

    %% Browser Environment
    subgraph "Browser Environment"
        direction TB
        HTML["HTML/CSS Scaffold"]:::htmlcss
        CSS["CSS Layout & Styles"]:::htmlcss
        Canvas["HTML5 Canvas (WebGL Viewport)"]:::htmlcss
        HTML -->|loads| CSS
        HTML -->|renders| Canvas
    end

    getUserMedia -->|stream| VideoStream["Video Stream"]:::data
    VideoStream -->|input| MediaPipeScript["MediaPipe Hands CDN"]:::external
    MediaPipeScript -->|provides| MediaPipe["MediaPipe Hands Pipeline"]:::ml
    MediaPipe -->|outputs landmarks| Landmarks["Hand Landmarks"]:::data

    %% Orchestration Layer
    subgraph "Application Logic (main.js)"
        direction TB
        MainJS["JavaScript Orchestration Layer"]:::logic
        RAFLoop["requestAnimationFrame Loop"]:::data
        ParticleSystem["3D Particle System"]:::render
        ThreeRenderer["Three.js Renderer & WebGL Context"]:::render
        Landmarks --> MainJS
        MainJS -->|calls| RAFLoop
        RAFLoop -->|updates| ParticleSystem
        RAFLoop -->|renders via| ThreeRenderer
        ThreeRenderer -->|draws to| Canvas
    end

    %% External Libraries
    subgraph "External Libraries"
        direction TB
        ThreeScript["Three.js CDN"]:::external
    end

    HTML -->|script include| MediaPipeScript
    HTML -->|script include| ThreeScript
    ThreeScript --> ThreeRenderer
    MediaPipeScript --> MediaPipe

    %% Documentation
    README["README.md"]:::doc

    %% Click Events
    click HTML "https://github.com/danielrobertdinu/the-force/blob/main/index.html"
    click Canvas "https://github.com/danielrobertdinu/the-force/blob/main/index.html"
    click CSS "https://github.com/danielrobertdinu/the-force/blob/main/styles.css"
    click MainJS "https://github.com/danielrobertdinu/the-force/blob/main/main.js"
    click MediaPipeScript "https://github.com/danielrobertdinu/the-force/blob/main/index.html"
    click MediaPipe "https://github.com/danielrobertdinu/the-force/blob/main/main.js"
    click ThreeScript "https://github.com/danielrobertdinu/the-force/blob/main/index.html"
    click ThreeRenderer "https://github.com/danielrobertdinu/the-force/blob/main/main.js"
    click ParticleSystem "https://github.com/danielrobertdinu/the-force/blob/main/main.js"
    click README "https://github.com/danielrobertdinu/the-force/blob/main/README.md"

    %% Styles
    classDef hardware fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef htmlcss fill:#add8e6,stroke:#333,stroke-width:1px
    classDef ml fill:#90ee90,stroke:#333,stroke-width:1px
    classDef render fill:#ffa500,stroke:#333,stroke-width:1px
    classDef logic fill:#f0e68c,stroke:#333,stroke-width:1px
    classDef data fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef doc fill:#ffeecc,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
