# vasturiano/force-graph architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source, client‐side JavaScript library (“force-graph”) that provides a web component to render 2D force-directed graphs on an HTML5 canvas.
- It’s not a full-stack app but rather a visualization tool built atop the d3-force physics engine, packaged for NPM and usable directly in the browser or via frameworks (e.g., React).

##### File structure
- Top-level configs and build scripts:
– .babelrc (Babel transpiler settings)
– rollup.config.js / rollup.config.dev.js (bundle definitions)
– package.json (dependencies, build commands)
- src/: ES module source code split into:
– canvas-force-graph.js (main renderer + API)
– force-graph.js (entry point façade)
– force-graph.css (default styles)
– index.js / index.d.ts (TypeScript declarations)
- example/: dozens of static HTML demos feeding sample JSON into the built bundle
- CI, linting, issue templates, LICENSE, README

##### README for additional insights
- Core dependencies: d3-force for simulation, HTML5 canvas for rendering
- Illustrates features: node/link styling, interactivity, DAG modes, custom rendering hooks, performance options
- Usage pattern: import ForceGraph, instantiate with a container DOM element, call .graphData() and chain config methods

a. Build & packaging pipeline (offline/build time)
- SOURCE (src/*.js, .css)
→ Babel (transpile ES6+)
→ Rollup (bundle, tree-shake, minify)
→ OUTPUT (dist/force-graph.umd.js, ES module bundle, type definitions)
- package.json → NPM package registry
b. Runtime in Browser (client)
- User Code (app.js or script tag)
– Imports ForceGraph from NPM or CDN
– Calls `new ForceGraph(container)` → returns graph instance
– Invokes chainable setters (`.graphData()`, `.nodeColor()`, etc.)
- ForceGraph Library
– API façade (index.js)
– Internal state manager (kapsule)
– Exposes hooks to configure d3-force simulation, canvas callbacks, events
- d3-force Engine
– Simulates physics (forces, ticks)
– Emits “tick” events → positions updated
- Canvas Renderer
– Post-render hook → custom overlays
- Interaction Tracker
– Offscreen “pointer canvas” painting for hit-testing nodes/links
– Mouse events → onNodeHover/Click, onLinkHover/Click, zoom/pan handlers
- User Callback Handlers
– User-provided functions invoked on clicks, drags, engine stop, etc.

##### Architectural patterns & design principles
- Modular ES6 code + utility modules (SINGLE RESPONSIBILITY)
- Declarative, chainable API (FLUENT INTERFACE)
- Event-driven flow between simulation, rendering, user callbacks (PUBLISH-SUBSCRIBE)
- Separation between simulation logic (d3-force) and view (canvas)
- Build system abstracts transpilation and bundling (BUILD-TIME vs RUN-TIME)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        BabelCFG[".babelrc"]:::build
        RollupCFG["rollup.config.js / rollup.config.dev.js"]:::build
        PackageJSON["package.json"]:::build
        Babel["Babel"]:::build
        Rollup["Rollup"]:::build
        Dist["dist/force-graph.umd.js<br/>ES Module Bundle<br/>Type Definitions"]:::build
        NPM["NPM Registry"]:::external
    end

    BabelCFG --> Babel
    RollupCFG --> Rollup
    PackageJSON --> Rollup
    Babel --> Rollup
    Rollup --> Dist
    Dist --> NPM

    %% Examples
    Examples["example/"]:::user
    Examples --> Dist

    %% Runtime in Browser
    subgraph "Runtime (Browser)"
        UserCode["User Code<br/>(app.js or script tag)"]:::user
        ForceGraphAPI["ForceGraph API<br/>(src/force-graph.js)"]:::core
        Kapsule["Kapsule State Manager<br/>(src/kapsule-link.js)"]:::core
        CanvasImpl["Canvas Renderer<br/>(src/canvas-force-graph.js)"]:::core
        UtilsColor["Color Utils<br/>(src/color-utils.js)"]:::core
        UtilsDag["DAG Depths<br/>(src/dagDepths.js)"]:::core
        StyleCSS["Stylesheet<br/>(src/force-graph.css)"]:::core
        IndexJS["Module Index<br/>(src/index.js,<br/>src/index.d.ts)"]:::core
        D3Force["d3-force Engine"]:::external
        CanvasAPI["HTML5 Canvas API"]:::runtime
        DOM["DOM (Canvas Element)"]:::runtime
        Interaction["Interaction Tracker"]:::runtime
        Callbacks["User Callback Handlers"]:::runtime
    end

    Dist --> UserCode
    UserCode -->|imports| ForceGraphAPI
    ForceGraphAPI --> IndexJS
    ForceGraphAPI --> Kapsule
    ForceGraphAPI -->|uses| UtilsColor
    ForceGraphAPI -->|uses| UtilsDag
    ForceGraphAPI --> CanvasImpl
    CanvasImpl -->|calls| D3Force
    D3Force -->|tick events| CanvasImpl
    CanvasImpl --> CanvasAPI
    CanvasAPI --> DOM
    DOM --> Interaction
    Interaction -->|mouse events| ForceGraphAPI
    ForceGraphAPI --> Callbacks
    Callbacks --> UserCode

    %% Click Events
    click BabelCFG "https://github.com/vasturiano/force-graph/blob/master/.babelrc"
    click RollupCFG "https://github.com/vasturiano/force-graph/blob/master/rollup.config.js"
    click RollupCFG "https://github.com/vasturiano/force-graph/blob/master/rollup.config.dev.js"
    click PackageJSON "https://github.com/vasturiano/force-graph/blob/master/package.json"
    click ForceGraphAPI "https://github.com/vasturiano/force-graph/blob/master/src/force-graph.js"
    click Kapsule "https://github.com/vasturiano/force-graph/blob/master/src/kapsule-link.js"
    click CanvasImpl "https://github.com/vasturiano/force-graph/blob/master/src/canvas-force-graph.js"
    click UtilsColor "https://github.com/vasturiano/force-graph/blob/master/src/color-utils.js"
    click UtilsDag "https://github.com/vasturiano/force-graph/blob/master/src/dagDepths.js"
    click StyleCSS "https://github.com/vasturiano/force-graph/blob/master/src/force-graph.css"
    click IndexJS "https://github.com/vasturiano/force-graph/blob/master/src/index.js"
    click IndexJS "https://github.com/vasturiano/force-graph/blob/master/src/index.d.ts"
    click Examples "https://github.com/vasturiano/force-graph/tree/master/example/"

    %% Styles
    classDef build fill:#f2f2f2,stroke:#888,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef external fill:#d4edda,stroke:#276749,stroke-width:1px
    classDef runtime fill:#ffe5b4,stroke:#cc8400,stroke-width:1px
    classDef user fill:#f3e6ff,stroke:#800080,stroke-width:1px
```
