# vasturiano/react-force-graph architecture

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

- Interactive diagram: https://gitdiagram.com/vasturiano/react-force-graph
- Repository: https://github.com/vasturiano/react-force-graph

## Overview

Based on our analysis of both the file tree and README, this project is a library that provides React bindings for a suite of force-directed graph visualization components. These components expose four separate packages for 2D, 3D, VR, and AR graph rendering, all of which share a similar API. The examples supplied in the “example” folder help demonstrate how each component is used, and the source code in the “src/packages” directory is organized as a monorepo containing each React package separately.

##### Main Components
- Library Packages – These are the core React components:
– react-force-graph-2d (2D Canvas – HTML based)
– react-force-graph-3d (3D with Three.js / WebGL)
– react-force-graph-vr (3D with VR support using A-Frame)
– react-force-graph-ar (AR using AR.js)
- Core Graph Data and Simulation Engine – The library consumes a generic graph data structure (nodes and links) and uses physics engines (primarily d3-force-3d and optionally ngraph) to simulate force-directed layouts.
- Rendering Backends – Depending on the package, the rendering technology varies:
– 2D: HTML5 Canvas
– 3D/VR/AR: Three.js-based rendering and additional VR/AR frameworks (A-Frame, AR.js)
- Build/Packaging Infrastructure – Include a component illustrating the monorepo structure (the “src/packages” folder) together with Rollup configuration and transpilation (files like rollup.config.js and .babelrc).

##### Relationships and Data Flow
- An input “Graph Data” block that provides dynamic data (nodes and links in JSON format) to the React components.
- Link the “Graph Data” to the “Simulation Engine” (i.e., d3-force-3d or ngraph). Then, display its connection to each “Rendering Engine” (Canvas for 2D; Three.js based for 3D, VR, AR).
- That the React bindings are essentially wrappers that map properties and events from React props onto the internal force simulation and rendering lifecycle.
- How events (node click, drag, hover) propagate from the rendered output back to user-defined callbacks.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize the shared interfaces across the four separate packages.
- Separation of Concerns: Clearly separate the graph data handling (physics engine) and the rendering layer (Canvas/Three.js) while showing that the React components form a thin presentation layer.
- Monorepo Organization: Include a logical representation of how multiple packages share common configurations (e.g., rollup and type definitions), indicating both the “src” directory and sub-packages.
- Extensibility: Highlight the customization points – for example, custom rendering (nodeCanvasObject, nodeThreeObject), custom event handlers, and custom simulation parameters.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Components
    GD["Graph Data Input (JSON)"]:::data
    FS["Force Simulation Engine (d3-force-3d/ngraph)"]:::sim
    IH["Interaction Handlers (click,drag,hover)"]:::interaction
    BP["Build & Packaging Infrastructure"]:::build
    EX["Example/Demo Applications"]:::example
    LIBUSE["Library Usage"]:::usage

    %% External Rendering Backends
    CANVAS["HTML5 Canvas"]:::render
    THREE["Three.js"]:::render
    AFRAME["A-Frame"]:::render
    ARJS["AR.js"]:::render

    %% React Force Graph Library Packages
    subgraph "React Force Graph Library"
        %% Package: 2D
        subgraph "Package: 2D"
            FG2D_SIM["r-force-graph-2d Simulation"]:::package
            FG2D_REND["r-force-graph-2d Rendering"]:::package
        end
        %% Package: 3D
        subgraph "Package: 3D"
            FG3D_SIM["r-force-graph-3d Simulation"]:::package
            FG3D_REND["r-force-graph-3d Rendering"]:::package
        end
        %% Package: VR
        subgraph "Package: VR"
            FGV_SIM["r-force-graph-vr Simulation"]:::package
            FGV_REND["r-force-graph-vr Rendering"]:::package
        end
        %% Package: AR
        subgraph "Package: AR"
            FGAR_SIM["r-force-graph-ar Simulation"]:::package
            FGAR_REND["r-force-graph-ar Rendering"]:::package
        end
    end

    %% Data Flow
    GD --> FS
    BP --> FS
    FS --> FG2D_SIM
    FS --> FG3D_SIM
    FS --> FGV_SIM
    FS --> FGAR_SIM

    FG2D_SIM --> FG2D_REND
    FG3D_SIM --> FG3D_REND
    FGV_SIM --> FGV_REND
    FGAR_SIM --> FGAR_REND

    FG2D_REND --> CANVAS
    FG3D_REND --> THREE
    FGV_REND --> AFRAME
    FGAR_REND --> ARJS

    %% Interaction Events Flow
    FG2D_REND --> IH
    FG3D_REND --> IH
    FGV_REND --> IH
    FGAR_REND --> IH

    %% Library Usage Flow for Demo Applications
    FG2D_REND --> LIBUSE
    FG3D_REND --> LIBUSE
    FGV_REND --> LIBUSE
    FGAR_REND --> LIBUSE
    BP --> LIBUSE
    LIBUSE --> EX

    %% Click Events for Component Mapping
    click FG2D_SIM "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-2d"
    click FG2D_REND "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-2d"
    click FG3D_SIM "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-3d"
    click FG3D_REND "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-3d"
    click FGV_SIM "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-vr"
    click FGV_REND "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-vr"
    click FGAR_SIM "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-ar"
    click FGAR_REND "https://github.com/vasturiano/react-force-graph/tree/master/src/packages/react-force-graph-ar"
    click FS "https://github.com/vasturiano/react-force-graph/blob/master/src/forcegraph-proptypes.js"
    click FS "https://github.com/vasturiano/react-force-graph/blob/master/src/index.js"
    click BP "https://github.com/vasturiano/react-force-graph/blob/master/.babelrc"
    click BP "https://github.com/vasturiano/react-force-graph/blob/master/rollup.config.js"
    click BP "https://github.com/vasturiano/react-force-graph/blob/master/rollup.config.dev.js"
    click BP "https://github.com/vasturiano/react-force-graph/blob/master/src/packages/react-force-graph-2d/rollup.config.js"
    click EX "https://github.com/vasturiano/react-force-graph/tree/master/example"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef sim fill:#C1E1C1,stroke:#333,stroke-width:1px;
    classDef interaction fill:#FFC0CB,stroke:#333,stroke-width:1px;
    classDef package fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef render fill:#FFFACD,stroke:#333,stroke-width:1px;
    classDef build fill:#F4A460,stroke:#333,stroke-width:1px;
    classDef example fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef usage fill:#E0EEEE,stroke:#333,stroke-width:1px;
```
