# davidgohel/ggiraph architecture

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

- Interactive diagram: https://gitdiagram.com/davidgohel/ggiraph
- Repository: https://github.com/davidgohel/ggiraph

## Overview

##### Project Type and Purpose
- `{ggiraph}` is an R package that extends **ggplot2** and implements an **htmlwidget** to render interactive SVG graphics in R, R Markdown and Shiny.
- It provides R functions (e.g., `geom_point_interactive()`, `girafe()`) that generate SVG markup with embedded `tooltip`, `onclick` and `data_id` attributes, and leverages C++ for SVG generation performance and JavaScript for client‑side interaction.

##### File‑Structure Analysis
- **R/** – R source code defining exported functions, ggproto extensions, roxygen comments, RcppExports.R.
- **src/** – C++ implementation: dsvg device, geometry handling, tinyxml2 XML writer. Build scripts (`Makevars*`) compile these into a shared library.
- **srcjs/** – Raw JavaScript modules for interaction primitives: hover, tooltip, selection, zoom.
- **inst/htmlwidgets/** – Packaged htmlwidget artifacts: `girafe.js`, `girafe.yaml`, third‑party libs (d3-bundle, save-svg-as-png, etc.).
- **man/** – Rd documentation files, figures.
- **examples/**, **inst/examples/**, **vignettes/** – Usage demos (R scripts, Shiny apps, R Markdown).
- **tests/**, **inst/tinytest/** – Unit and visual tests.
- **tools/** – Build helpers (packagejs Webpack config bundling JS/CSS, tinyxml2 patches).
- **.github/workflows/** – CI: R‑CMD‑check, pkgdown site, rhub, coverage.

##### Key Insights from README
- Under the hood: an **htmlwidget** + **ggplot2** extension.
- Interactive aesthetics (`tooltip`, `onclick`, `data_id`) augment ggplot layers; `girafe()` wraps a `ggplot` object into an HTML widget.
- Shiny integration: widget exposes selection events to the server via reactive values.

##### Main Components (
a. **User/Client**
- R console, R Markdown HTML output, or Shiny app running in a browser.
b. **R Session**
- Loads `{ggiraph}`, builds `ggplot` object with interactive geoms.
- Calls `girafe()` to export an htmlwidget.
c. **C++ Backend (Rcpp)**
- RcppExports layer → calls C++ functions in **src/**.
- `dsvg_dev.cpp` generates SVG + custom attributes via tinyxml2.
d. **htmlwidget Layer**
- Wraps generated SVG into an HTML document.
- Uses metadata from `inst/htmlwidgets/girafe.yaml` to link JS & CSS.
e. **JavaScript Runtime**
- Bundled JS in `inst/htmlwidgets/lib` + transpiled `srcjs` modules.
- Handles mouse events, tooltips, selections, zoom, onclick actions.
f. **Browser**
- Renders SVG and UI controls (toolbar).
- In Shiny: widget uses Shiny’s message protocol to send selection events back.
g. **Shiny Server (optional)**
- Receives input from widget, triggers reactive R code, possibly re‑rendering the widget.

##### Interactions and Data Flows
- R function → C++ → SVG markup → htmlwidget → HTML+JS → Browser
(render)
- Browser events (hover, click, selection) → JavaScript handlers → Shiny (via WebSocket) or direct JS callbacks.
(user interaction)
- In Shiny mode: UI input rebounds to R server → triggers reactivity → widget update.

##### Architectural Patterns and Design Principles
- **Layered architecture**: R API → native library → widget wrapper → client runtime.
- **Extension pattern**: builds on ggplot2’s ggproto system, injecting interactivity at the layer level.
- **Separation of concerns**: R for API, C++ for high‑performance SVG writing, JS for client interactions.
- **Modular JS**: custom modules (`srcjs`) bundled via Webpack (`tools/packagejs`).

##### Technologies and Frameworks
- R, ggplot2, htmlwidgets
- C++ (Rcpp) and tinyxml2
- JavaScript, D3.js, Webpack for bundling
- Shiny for server‑side reactivity
- Testing: tinytest, CI with GitHub Actions, codecov

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    User["User/Client<br>(R Console / HTML Output / Browser)"]:::r
    RSession("R Session"):::r
    Cpp["C++ Backend<br>(Rcpp & tinyxml2)"]:::cpp
    HTML["htmlwidget Wrapper"]:::widget
    JS["JavaScript Runtime"]:::js
    Browser["Browser"]:::browser
    Shiny["Shiny Server"]:::server

    %% Flow
    User -->|"invoke geom_*_interactive() & girafe()"| RSession
    RSession -->|"RcppExports"| Cpp
    Cpp -->|"SVG/XML output"| HTML
    HTML -->|"HTML + JS"| JS
    JS -->|"render SVG & handle events"| Browser
    Browser -->|"selection events (WebSocket)"| Shiny
    Shiny -->|"reactive inputs"| RSession

    %% File Groups Annotation
    subgraph "File Structure (Modules)" 
        direction TB
        Rfiles["R/"]:::files
        Cppfiles["src/"]:::files
        Widgetfiles["inst/htmlwidgets/"]:::files
        JSsrc["srcjs/"]:::files
        Bundled["inst/htmlwidgets/lib/"]:::files
        Webpack["tools/packagejs/"]:::files
        Tests["inst/tinytest/ & tests/"]:::files
        Examples["examples/, inst/examples/, vignettes/"]:::files
        Docs["man/"]:::files
        CI[".github/workflows/"]:::files
    end

    %% File Group Connections (annotations only)
    RSession --- Rfiles
    Cpp --- Cppfiles
    HTML --- Widgetfiles
    JS --- JSsrc
    JS --- Bundled
    JSsrc --- Webpack
    RSession --- Tests
    User --- Examples
    RSession --- Docs
    RSession --- CI

    %% Click Events
    click Rfiles "https://github.com/davidgohel/ggiraph/tree/master/R/"
    click Cppfiles "https://github.com/davidgohel/ggiraph/tree/master/src/"
    click Widgetfiles "https://github.com/davidgohel/ggiraph/tree/master/inst/htmlwidgets/"
    click JSsrc "https://github.com/davidgohel/ggiraph/tree/master/srcjs/"
    click Bundled "https://github.com/davidgohel/ggiraph/tree/master/inst/htmlwidgets/lib/"
    click Webpack "https://github.com/davidgohel/ggiraph/tree/master/tools/packagejs/"
    click Tests "https://github.com/davidgohel/ggiraph/tree/master/inst/tinytest/"
    click Tests "https://github.com/davidgohel/ggiraph/tree/master/tests/"
    click Examples "https://github.com/davidgohel/ggiraph/tree/master/examples/"
    click Examples "https://github.com/davidgohel/ggiraph/tree/master/inst/examples/"
    click Examples "https://github.com/davidgohel/ggiraph/tree/master/vignettes/"
    click Docs "https://github.com/davidgohel/ggiraph/tree/master/man/"
    click CI "https://github.com/davidgohel/ggiraph/tree/master/.github/workflows/"

    %% Legend
    subgraph Legend
        direction TB
        L1["<span style='color:#2ca02c'>&#9724;</span> R Layer"]:::r
        L2["<span style='color:#1f77b4'>&#9724;</span> C++ Layer"]:::cpp
        L3["<span style='color:#9467bd'>&#9724;</span> htmlwidget"]:::widget
        L4["<span style='color:#ff7f0e'>&#9724;</span> JS Runtime"]:::js
        L5["<span style='color:#8c564b'>&#9724;</span> Browser/Server"]:::server
    end

    %% Styles
    classDef r fill:#e8f5e9,stroke:#2ca02c,color:#2ca02c;
    classDef cpp fill:#e3f2fd,stroke:#1f77b4,color:#1f77b4;
    classDef widget fill:#f3e5f5,stroke:#9467bd,color:#9467bd;
    classDef js fill:#fff3e0,stroke:#ff7f0e,color:#ff7f0e;
    classDef browser fill:#fbe9e7,stroke:#8c564b,color:#8c564b;
    classDef server fill:#fbe9e7,stroke:#8c564b,color:#8c564b;
    classDef files fill:#ffffff,stroke:#aaaaaa,color:#333333,stroke-dasharray: 2 2;
    classDef Legend fill:#ffffff,stroke:#000000,color:#000000,stroke-dasharray: 1 1;
```
