# mnmxmx/fluid-three architecture

> Architecture diagram of the GitHub repository mnmxmx/fluid-three, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mnmxmx/fluid-three
- Repository: https://github.com/mnmxmx/fluid-three

## Overview

##### Main Components
- User Interface & Entry Point: Represent the “dist/index.html” as the web page that hosts the simulation’s WebGL canvas.
- WebGL Context & Core Rendering: Illustrate the “WebGL.js” module as the central piece that creates and manages the WebGL context. Also include the “ShaderPass.js” which likely encapsulates the logic for applying shaders during rendering.
- Simulation Engine: Group the simulation-related modules (Advection.js, Divergence.js, ExternalForce.js, Pressure.js, Poisson.js, Viscous.js) as processing stages. The “Simulation.js” module should appear as the orchestrator that sequentially calls these simulation steps.
- User Interaction and Controls: Include modules like “Controls.js” and “Mouse.js” to show how user input is handled and fed into the simulation (e.g., triggering ExternalForce).
- Utility and Event Handling: Show supporting modules such as “EventBus.js”, “math.js” and “utils.js”, which are used for communication between components and to perform mathematical operations required in the simulation.

##### Relationships and Interactions
- Simulation Loop: From “Simulation.js”, create a sequential flow that runs the simulation steps:
- Data flows from “Advection.js” → “Divergence.js” → “Pressure.js” → “Poisson.js” → “Viscous.js”.
- User Input: Show “Mouse.js” and “Controls.js” feeding data (like external forces) into the simulation loop (e.g., input going to “ExternalForce.js”).

##### Architectural Patterns
- Modular Design: Emphasize the separation of concerns where each simulation step is isolated in its own module.
- Data Flow/Processing Pipeline: Show iterative arrowed flow from one stage to the next within the simulation.
- GPU Offloading: Clearly delineate between JavaScript modules managing application logic and the GLSL shader modules managing GPU-accelerated computations.
- Build & Deployment: Indicate that the project is built using Webpack (webpack.config.js) and uses package management (package.json) to run the Node.js environment with Yarn for dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["User Interface (index.html)"]:::ui
    end

    %% Rendering Layer
    subgraph "Rendering Layer"
        WebGL["WebGL Context (WebGL.js)"]:::render
        ShaderPass["Shader Pass (ShaderPass.js)"]:::render
    end

    %% Simulation Engine Layer
    subgraph "Simulation Engine Layer"
        Simulation["Simulation Orchestrator (Simulation.js)"]:::sim
        ExternalForce["External Force Stage (ExternalForce.js)"]:::sim
        Advection["Advection Stage (Advection.js)"]:::sim
        Divergence["Divergence Stage (Divergence.js)"]:::sim
        Pressure["Pressure Stage (Pressure.js)"]:::sim
        Poisson["Poisson Stage (Poisson.js)"]:::sim
        Viscous["Viscous Stage (Viscous.js)"]:::sim
    end

    %% Shaders Layer
    subgraph "Shaders (GPU Computation)"
        AdvectionShader["Advection Shader (advection.frag)"]:::shader
        DivergenceShader["Divergence Shader (divergence.frag)"]:::shader
        ExternalForceShader["ExternalForce Shader (externalForce.frag)"]:::shader
        PressureShader["Pressure Shader (pressure.frag)"]:::shader
        PoissonShader["Poisson Shader (poisson.frag)"]:::shader
        ViscousShader["Viscous Shader (viscous.frag)"]:::shader
        ColorShader["Color Shader (color.frag)"]:::shader
        FaceVertexShader["Face Vertex Shader (face.vert)"]:::shader
        LineVertexShader["Line Vertex Shader (line.vert)"]:::shader
        MouseVertexShader["Mouse Vertex Shader (mouse.vert)"]:::shader
    end

    %% User Interaction Layer
    subgraph "User Interaction Layer"
        Controls["Controls (Controls.js)"]:::control
        MouseInteraction["Mouse (Mouse.js)"]:::control
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        EventBus["EventBus (EventBus.js)"]:::util
        MathUtil["Math Utilities (math.js)"]:::util
        Utils["General Utils (utils.js)"]:::util
    end

    %% Build & Deployment Layer
    subgraph "Build & Deployment"
        Webpack["Webpack Config (webpack.config.js)"]:::build
        PackageManagement["Package Management (package.json & Yarn)"]:::build
    end

    %% Connections: Main Flow
    UI -->|"initializes"| WebGL
    WebGL -->|"creates context"| ShaderPass
    ShaderPass -->|"render call"| Simulation
    Simulation -->|"triggers"| ExternalForce
    ExternalForce -->|"feeds into"| Advection
    Advection -->|"processes"| Divergence
    Divergence -->|"processes"| Pressure
    Pressure -->|"processes"| Poisson
    Poisson -->|"processes"| Viscous

    %% Connections: Simulation steps to their shaders
    ExternalForce ---|"uses"| ExternalForceShader
    Advection ---|"uses"| AdvectionShader
    Divergence ---|"uses"| DivergenceShader
    Pressure ---|"uses"| PressureShader
    Poisson ---|"uses"| PoissonShader
    Viscous ---|"uses"| ViscousShader

    %% Additional shaders (auxiliary GPU ops)
    ColorShader ---|"auxiliary"| FaceVertexShader
    FaceVertexShader ---|"auxiliary"| LineVertexShader
    LineVertexShader ---|"auxiliary"| MouseVertexShader

    %% Connections: User Interaction Feeds into Simulation External Force
    Controls -->|"input"| ExternalForce
    MouseInteraction -->|"input"| ExternalForce

    %% Utilities supporting Simulation and User Interaction
    EventBus ---|"mediates events"| Simulation
    EventBus ---|"mediates events"| Controls
    MathUtil ---|"calculates"| Simulation
    Utils ---|"provides helper functions"| Simulation

    %% Build Tools influencing Simulation Engine Setup
    PackageManagement -->|"configures"| Webpack
    Webpack -->|"builds"| Simulation

    %% Click Events for Components (Paths Hidden from Diagram)
    click UI "https://github.com/mnmxmx/fluid-three/blob/master/dist/index.html"
    click WebGL "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/WebGL.js"
    click ShaderPass "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/ShaderPass.js"
    click Simulation "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Simulation.js"
    click ExternalForce "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/ExternalForce.js"
    click Advection "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Advection.js"
    click Divergence "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Divergence.js"
    click Pressure "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Pressure.js"
    click Poisson "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Poisson.js"
    click Viscous "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Viscous.js"
    click AdvectionShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/advection.frag"
    click DivergenceShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/divergence.frag"
    click ExternalForceShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/externalForce.frag"
    click PressureShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/pressure.frag"
    click PoissonShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/poisson.frag"
    click ViscousShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/viscous.frag"
    click ColorShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/color.frag"
    click FaceVertexShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/face.vert"
    click LineVertexShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/line.vert"
    click MouseVertexShader "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/glsl/sim/mouse.vert"
    click Controls "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Controls.js"
    click MouseInteraction "https://github.com/mnmxmx/fluid-three/blob/master/js/modules/Mouse.js"
    click EventBus "https://github.com/mnmxmx/fluid-three/blob/master/js/utils/EventBus.js"
    click MathUtil "https://github.com/mnmxmx/fluid-three/blob/master/js/utils/math.js"
    click Utils "https://github.com/mnmxmx/fluid-three/blob/master/js/utils/utils.js"

    %% Styles
    classDef ui fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef render fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
    classDef sim fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef shader fill:#fdebd0,stroke:#e67e22,stroke-width:2px;
    classDef control fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef util fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef build fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
```
