# robert-haas/gravis architecture

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

- Interactive diagram: https://gitdiagram.com/robert-haas/gravis
- Repository: https://github.com/robert-haas/gravis

## Overview

##### Project type and purpose
- Gravis is a Python library for graph visualization and conversion.
- It takes input graphs (from NetworkX, igraph, graph-tool, etc.), converts them into a generic JSON graph format (GJGF), and renders them as interactive visualizations using D3, vis-network, and 3D Force Graph (three.js).

##### File structure
- Top-level package:
- gravis/
– _internal/conversion: logic for converting various graph inputs into GJGF
– _internal/plotting: modules (d3.py, vis.py, three.py) that take GJGF and produce HTML/JS visualizations via template_system.
– _internal/utils: argument parsing, OS helpers, web helpers.
- Supporting directories:
- docs/: Sphinx documentation source and generated theme assets
- examples/: Jupyter notebooks demonstrating usage with sample data
- tests/: pytest-based automated tests
- Build and distribution: setup.py, setup.cfg, Makefile, tox.ini, MANIFEST.in.

##### README for additional insights
- Confirms it’s a PyPI-distributed, Apache-licensed package built with Sphinx.

##### Detail without overcomplicating
- Plotting engine separately.
- Template system as a shared resource used by all plotting backends.
- Documentation and test suites as ancillary packages but separated from the core runtime path.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input Layer"
        direction TB
        UserCode["User Code / Examples"]:::python
        subgraph "External Graph Libraries"
            direction TB
            NX["NetworkX"]:::external
            IG["igraph"]:::external
            GT["graph-tool"]:::external
            SN["snap"]:::external
            NK["NetworkIt"]:::external
            PT["PyNtacle"]:::external
        end
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        API["Core API<br/>(gravis/__init__.py)"]:::python
        subgraph "Conversion Layer" 
            direction TB
            ConvDir["gravis._internal.conversion"]:::python
            ConvertPy["convert.py"]:::python
            IntConv["_internal.py"]:::python
        end
        subgraph "Utility Modules"
            direction TB
            UtilsDir["gravis._internal.utils"]:::python
            ArgsPy["args.py"]:::python
            OSPy["operating_system.py"]:::python
            WebPy["web.py"]:::python
        end
    end

    %% Data Layer
    GJGF["Generic JSON Graph Format (GJGF)"]:::data

    %% Presentation Layer
    subgraph "Plotting Layer"
        direction TB
        PlotDir["gravis._internal.plotting"]:::python
        D3Py["d3.py"]:::python
        VisPy["vis.py"]:::python
        ThreePy["three.py"]:::python
        DataStruct["data_structures.py"]:::python
        Rendering["rendering.py"]:::python
        TemplateSys["template_system.py"]:::python
        subgraph Templates
            direction TB
            D3HTML["d3.html"]:::support
            VisHTML["vis.html"]:::support
            ThreeHTML["three.html"]:::support
        end
        subgraph "Bundled JS Libraries"
            direction TB
            D3Lib["d3"]:::external
            VisLib["vis-network"]:::external
            ThreeLib["three"]:::external
            Force3D["3d-force-graph"]:::external
            RequireJS["require"]:::external
        end
    end

    %% Output Layer
    Browser["Web Browser / Notebook"]:::external

    %% Ancillary Components
    subgraph "Documentation"
        direction TB
        DocsDir["docs/source"]:::support
    end
    subgraph "Test Suite"
        direction TB
        TestsDir["tests"]:::support
    end

    %% Build Metadata
    Meta["setup.py,<br/>setup.cfg,<br/>MANIFEST.in,<br/>Makefile,<br/>tox.ini"]:::support

    %% Connections
    UserCode -->|imports API| API
    NX -->|input graph| API
    IG -->|input graph| API
    GT -->|input graph| API
    SN -->|input graph| API
    NK -->|input graph| API
    PT -->|input graph| API

    API -->|dispatch| ConvDir
    ConvDir --> ConvertPy
    ConvDir --> IntConv
    ConvDir -->|produces| GJGF

    API -->|uses| UtilsDir
    UtilsDir --> ArgsPy
    UtilsDir --> OSPy
    UtilsDir --> WebPy

    GJGF -->|injected into| TemplateSys
    TemplateSys --> D3Py
    TemplateSys --> VisPy
    TemplateSys --> ThreePy

    D3Py --> D3HTML
    VisPy --> VisHTML
    ThreePy --> ThreeHTML

    D3Py -->|includes| D3Lib
    VisPy -->|includes| VisLib
    ThreePy -->|includes| ThreeLib
    ThreePy -->|includes| Force3D
    ThreePy -->|includes| RequireJS

    D3HTML --> Browser
    VisHTML --> Browser
    ThreeHTML --> Browser

    DocsDir -.-> API
    DocsDir -.-> D3Py
    DocsDir -.-> VisPy
    DocsDir -.-> ThreePy

    TestsDir -.-> ConvDir
    TestsDir -.-> D3Py
    TestsDir -.-> VisPy
    TestsDir -.-> ThreePy

    Meta -.-> API

    %% Click Events
    click ConvDir "https://github.com/robert-haas/gravis/tree/master/gravis/_internal/conversion/"
    click ConvertPy "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/conversion/convert.py"
    click IntConv "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/conversion/_internal.py"
    click UtilsDir "https://github.com/robert-haas/gravis/tree/master/gravis/_internal/utils/"
    click ArgsPy "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/utils/args.py"
    click OSPy "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/utils/operating_system.py"
    click WebPy "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/utils/web.py"
    click API "https://github.com/robert-haas/gravis/blob/master/gravis/__init__.py"
    click PlotDir "https://github.com/robert-haas/gravis/tree/master/gravis/_internal/plotting/"
    click D3Py "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/d3.py"
    click VisPy "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/vis.py"
    click ThreePy "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/three.py"
    click DataStruct "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/data_structures.py"
    click Rendering "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/rendering.py"
    click TemplateSys "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/template_system.py"
    click D3HTML "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/templates/d3.html"
    click VisHTML "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/templates/vis.html"
    click ThreeHTML "https://github.com/robert-haas/gravis/blob/master/gravis/_internal/plotting/templates/three.html"
    click DocsDir "https://github.com/robert-haas/gravis/tree/master/docs/source/"
    click TestsDir "https://github.com/robert-haas/gravis/tree/master/tests/"

    %% Styles
    classDef python fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef external fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20;
    classDef data fill:#ffe0b2,stroke:#ef6c00,color:#e65100;
    classDef support fill:#e0e0e0,stroke:#616161,color:#212121;
```
