# brunoimbrizi/interactive-particles architecture

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

- Interactive diagram: https://gitdiagram.com/brunoimbrizi/interactive-particles
- Repository: https://github.com/brunoimbrizi/interactive-particles

## Overview

##### Main Project Components
- HTML Shell: The src/index.html file serves as the entry point for the application.
- JavaScript Application Logic: Found in the src/scripts directory, this includes:
– App.js & index.js: Likely the main entry and initial configuration of the application.
– GUI Subsystem (src/scripts/gui/GUIView.js): Responsible for the interactive control panel (using libraries such as ControlKit).
– WebGL Subsystem (src/scripts/webgl): Houses the main modules for rendering the 3D scene, including:
– WebGLView.js: Sets up the Three.js scene, camera, and renderer.
– Controls (InteractiveControls.js): Manages user inputs (mouse/touch) for interacting with the particles.
– Particles (Particles.js and TouchTexture.js): Handles the particle system and the off-screen texture reactions.
- Utility Modules: Located in src/scripts/utils, these include helper modules for easing, events, fetching data, and mathematical operations.
- Shaders: Under src/shaders, the GLSL files (particle.frag and particle.vert) define the visual effects in the particle system.
- Configuration and Environment Settings: The config directory (with common.js, dev.js, prod.js) provides environment-specific settings.
- Static Assets: The static directory holds CSS stylesheets and images for presentation.

##### Relationships and Interactions
- The index.html supplies the DOM that loads your scripts.
- The core App (App.js) acts as the orchestrator, initializing both the GUI and WebGL Views.
- The WebGL module, via its InteractiveControls, captures user inputs and passes them to the particle system for real-time reactive animations.
- The Utility modules provide support functions used across the application, so they’d be connected to both the GUI and WebGL modules.
- Shaders are tightly coupled with the WebGL display; they are loaded and used by WebGLView.js and Particle modules to create GPU-based visual effects.

##### Architectural Patterns and Design Principles
- Modularization: The code is broken into distinct modules based on functionality (GUI, WebGL, utilities), which aids in maintainability and separation of concerns.
- Configuration Management: Environment-specific configurations (dev vs. prod) are housed in the config directory, indicating a clear separation between runtime environments.
- Use of External Libraries: Three.js provides the WebGL wrapper; gsap is used for advanced animations; glslify helps modularize shader code; and stats.js monitors performance.
- This design closely follows a component-based architecture, where each module (or component) is independently responsible for one feature (rendering, input handling, utility functions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    subgraph "Entry Point"
        HTML["index.html (HTML Shell)"]:::html
    end

    %% Main Application Logic
    subgraph "Main App"
        APP["App.js"]:::app
        INDEX["index.js"]:::app
    end

    %% GUI Subsystem
    subgraph "GUI Subsystem"
        GUI["GUIView.js"]:::gui
    end

    %% WebGL Subsystem
    subgraph "WebGL Subsystem"
        WEBGLVIEW["WebGLView.js"]:::webgl
        CONTROLS["InteractiveControls.js"]:::webgl
        PARTICLES["Particles.js"]:::webgl
        TOUCH["TouchTexture.js"]:::webgl
    end

    %% Utility Modules
    subgraph "Utilities"
        UTILS["Utils Modules"]:::utils
    end

    %% Shaders
    subgraph "Shaders"
        FRAG["particle.frag"]:::shaders
        VERT["particle.vert"]:::shaders
    end

    %% Configuration
    subgraph "Configuration"
        CONFIG["config/"]:::config
    end

    %% Static Assets
    subgraph "Static Assets"
        STATIC["static/"]:::assets
    end

    %% External Libraries
    subgraph "External Libraries"
        THREE["Three.js"]:::external
        GSAP["gsap"]:::external
        GLSLIFY["glslify"]:::external
        STATS["stats.js"]:::external
    end

    %% Data Flow and Interactions
    HTML -->|"loads"| APP
    INDEX -->|"initializes"| APP
    APP -->|"orchestrates"| GUI
    APP -->|"orchestrates"| WEBGLVIEW
    GUI -->|"control_signals"| WEBGLVIEW
    WEBGLVIEW -->|"handles_input"| CONTROLS
    WEBGLVIEW -->|"renders_scene"| PARTICLES
    CONTROLS -->|"passes_user_input"| PARTICLES
    WEBGLVIEW -->|"loads_shader"| FRAG
    WEBGLVIEW -->|"loads_shader"| VERT
    UTILS -->|"support_functions"| GUI
    UTILS -->|"support_functions"| WEBGLVIEW
    CONFIG -->|"configures"| APP
    STATIC -->|"provides_styles/images"| HTML

    %% External Library Integrations
    THREE -->|"renders_with"| WEBGLVIEW
    GSAP -->|"animates"| PARTICLES
    GLSLIFY -->|"processes"| FRAG
    GLSLIFY -->|"processes"| VERT
    STATS -->|"monitors"| APP

    %% Click Events
    click HTML "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/index.html"
    click APP "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/scripts/App.js"
    click INDEX "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/scripts/index.js"
    click GUI "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/scripts/gui/GUIView.js"
    click WEBGLVIEW "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/scripts/webgl/WebGLView.js"
    click CONTROLS "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/scripts/webgl/controls/InteractiveControls.js"
    click PARTICLES "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/scripts/webgl/particles/Particles.js"
    click TOUCH "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/scripts/webgl/particles/TouchTexture.js"
    click UTILS "https://github.com/brunoimbrizi/interactive-particles/tree/master/src/scripts/utils/"
    click FRAG "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/shaders/particle.frag"
    click VERT "https://github.com/brunoimbrizi/interactive-particles/blob/master/src/shaders/particle.vert"
    click CONFIG "https://github.com/brunoimbrizi/interactive-particles/tree/master/config/"
    click STATIC "https://github.com/brunoimbrizi/interactive-particles/tree/master/static/"

    %% Styles
    classDef html fill:#f6d186,stroke:#333,stroke-width:2px;
    classDef app fill:#c9daf8,stroke:#333,stroke-width:2px;
    classDef gui fill:#d9ead3,stroke:#333,stroke-width:2px;
    classDef webgl fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef utils fill:#fff2cc,stroke:#333,stroke-width:2px;
    classDef shaders fill:#f4cccc,stroke:#333,stroke-width:2px;
    classDef config fill:#cfe2f3,stroke:#333,stroke-width:2px;
    classDef assets fill:#d9d2e9,stroke:#333,stroke-width:2px;
    classDef external fill:#d9d9d9,stroke:#333,stroke-width:2px;
```
