Overview

relation-graph is a cross-platform graph visualization and editing library designed for building knowledge graphs, organizational charts, network topologies, and other relationship-based data visualizations. The system provides a framework-agnostic core with specialized adapters for Vue 2, Vue 3, React, Svelte, and Web Components.

This document provides a high-level introduction to the system architecture, core components, and how the different platform packages share common functionality. For specific implementation details of individual subsystems, refer to:

Core architecture and class hierarchy: Core Architecture
Data management: Data Management System
Layout algorithms: Layout System
Rendering pipeline: Rendering System
User interactions: User Interaction & Events

Purpose and Capabilities

The library enables developers to:

Visualize complex relationships between entities using nodes and lines/edges
Apply automatic layouts using force-directed, tree-based, circular, and hybrid algorithms
Interact with graphs through panning, zooming, node dragging, and selection
Edit graph structure by creating, updating, and deleting nodes and lines interactively
Customize rendering using framework-specific slot systems for nodes and lines
Handle large datasets with viewport culling and canvas-based performance modes

System Architecture

Multi-Platform Package Structure

The system is distributed as five separate npm packages, each targeting a specific JavaScript framework. All packages share the same core business logic but provide framework-specific UI components and reactive data integration.

graph TB
    subgraph "Published npm Packages"
        Vue2["@relation-graph/vue2
Vue 2.x wrapper"]
        Vue3["@relation-graph/vue
Vue 3.x wrapper"]
        React["@relation-graph/react
React wrapper"]
        Svelte["@relation-graph/svelte
Svelte wrapper"]
        WebComp["@relation-graph/web-components
Framework-agnostic"]
    end
    
    subgraph "Shared Core Layer"
        Core["RelationGraphCore
packages/relation-graph-models/"]
        Types["Type Definitions
packages/types.ts"]
        Layouts["Layout Engines
packages/relation-graph-models/layouters/"]
        Utils["Utilities & Data Providers
packages/relation-graph-models/"]
    end
    
    Vue2 --> Core
    Vue3 --> Core
    React --> Core
    Svelte --> Core
    WebComp --> Core
    
    Core --> Types
    Core --> Layouts
    Core --> Utils

Package Locations:

Vue 2 package: platforms/vue2/
Vue 3 package: platforms/vue3/
React package: platforms/react/
Svelte package: platforms/svelte/
Web Components package: platforms/web-components/

Core Instance Architecture

The RelationGraphCore class is constructed through a progressive enhancement pattern, where approximately 20 classes each add specific capabilities through linear inheritance. This allows modular organization of functionality while maintaining a single cohesive API.

graph LR
    Base["RelationGraphBase
Event system"]
    View["RelationGraphWith1View
DOM & coordinates"]
    Data["RelationGraphWith2Data
Data management"]
    Options["RelationGraphWith3Options1Update
Configuration"]
    Line["RelationGraphWith4Line
Line rendering"]
    Zoom["RelationGraphWith5Zoom
Zoom control"]
    Layout["RelationGraphWith6Layout
Layout algorithms"]
    Event["RelationGraphWith7Event
User interactions"]
    Editing["RelationGraphWith91Editing
Edit mode"]
    API["RelationGraphWith99API
Public API"]
    Final["RelationGraphCore"]
    
    Base --> View --> Data --> Options --> Line
    Line --> Zoom --> Layout --> Event --> Editing
    Editing --> API --> Final

Each class in the chain adds specific functionality:

RelationGraphBase: Event emission and UUID generation
RelationGraphWith1View: Coordinate transformations between canvas, viewport, and client spaces
RelationGraphWith2Data: Reactive data initialization and CRUD operations
RelationGraphWith4Line: Line path generation and rendering calculations
RelationGraphWith7Event: Mouse and touch event handling
RelationGraphWith91Editing: Node selection, resizing, and line editing

Data Model

The system uses a transformation pipeline to convert user-provided JSON data into runtime-enhanced objects optimized for rendering and interaction.

Core Data Types

Type	Purpose	Location
`JsonNode`	User input format for nodes	packages/types.ts:206-241
`JsonLine`	User input format for lines	packages/types.ts:296-340
`RGNode`	Runtime node with layout data	packages/types.ts:245-276
`RGLine`	Runtime line object	packages/types.ts:356-359
`RGLink`	Derived object connecting line to nodes	packages/types.ts:372-381
`RGFakeLine`	Lines with non-node endpoints	packages/types.ts:347-351

Type Relationships

graph TD
    subgraph "User Input Types"
        JsonNode["JsonNode
{id, text, x, y, ...}"]
        JsonLine["JsonLine
{from, to, text, ...}"]
    end
    
    subgraph "Runtime Types"
        RGNode["RGNode
+ lot: layout data
+ rgShouldRender
+ el_W, el_H"]
        RGLine["RGLine
+ isReverse"]
        RGLink["RGLink
+ fromNode
+ toNode
+ currentLineIndex"]
    end
    
    subgraph "Internal Data Structure"
        RGGraphData["RGGraphData
{nodes: RGNode[]
normalLines: RGLine[]
fakeLines: RGFakeLine[]}"]
    end
    
    JsonNode -->|"json2Node()"| RGNode
    JsonLine -->|"json2Line()"| RGLine
    RGLine -->|"linked with nodes"| RGLink
    RGNode --> RGGraphData
    RGLine --> RGGraphData

Data Transformation Functions:

Node conversion: packages/relation-graph-models/data/RGNodeDataUtils.ts
Line conversion: packages/relation-graph-models/data/RGLineDataUtils.ts:3-86

Component Organization

The rendering system consists of framework-specific UI components that delegate business logic to the shared core instance.

Primary Components

graph TB
    subgraph "User Application"
        App["Application Code"]
    end
    
    subgraph "Top-Level Component"
        RG["RelationGraph
Main entry component
Creates RelationGraphCore"]
    end
    
    subgraph "UI Layout Components"
        RGUI["RelationGraphUI
Orchestrates layout"]
        Canvas["RGCanvas
SVG/Canvas rendering surface"]
        Toolbar["RGToolBar
Zoom/layout controls"]
        MiniView["RGMiniView
Overview navigator"]
    end
    
    subgraph "Content Components"
        Node["RGNode
Node renderer"]
        LinePath["RGLinePath
Line path SVG"]
        LineText["RGLineText
Line labels"]
        ConnectTarget["RGConnectTarget
Connection points"]
    end
    
    subgraph "Editing Components"
        EditNode["RGEditingNodeController
Selection UI"]
        EditLine["RGEditingLineController
Line editing UI"]
        RefLines["RGReferenceLines
Alignment guides"]
    end
    
    App --> RG
    RG --> RGUI
    RGUI --> Canvas
    RGUI --> Toolbar
    RGUI --> MiniView
    Canvas --> Node
    Canvas --> LinePath
    Canvas --> LineText
    Node --> ConnectTarget
    RGUI --> EditNode
    RGUI --> EditLine
    RGUI --> RefLines

Component Implementations:

Vue components: platforms/vue3/src/components/, platforms/vue2/src/components/
React components: platforms/react/src/components/
Svelte components: platforms/svelte/src/components/

Configuration and Options

The system uses a two-tier configuration structure:

Type	Purpose	Mutability
`RGOptions`	User-provided partial configuration	Partial
`RGOptionsInited`	Complete configuration with defaults	Immutable after init
`RGOptionsFull`	Runtime state + configuration	Mutable during runtime

Key configuration categories:

Layout options: layout.layoutName, layout.layoutDirection, layout-specific parameters
Visual defaults: defaultNodeColor, defaultLineShape, defaultLineWidth
Interaction settings: disableDragNode, wheelEventAction, dragEventAction
Performance modes: performanceMode (enables viewport culling)

Layout System

The library provides multiple automatic layout algorithms, each implementing the RGLayout interface:

Layout Class	Layout Name	Use Case
`RGTreeLayout`	`tree`	Hierarchical tree structures
`RGForceLayout`	`force`	Physics-based simulations
`RGCenterLayout`	`center`	Radial layouts around center node
`RGCircleLayout`	`circle`	Circular arrangement
`RGFixedLayout`	`fixed`	No automatic positioning
`RGSmartTreeLayout`	`smart-tree`	Tree + force hybrid
`RGIOTreeLayout`	`io-tree`	Input-output bidirectional tree
`RGFolderLayout`	`folder`	File system hierarchy

All layout classes are located in: packages/relation-graph-models/layouters/

Reactive Data Integration

Each framework package includes a specialized data provider that bridges the framework’s reactive system with the core’s data model:

Data Provider	Framework	Location
`RGDataProvider4Vue2`	Vue 2	Uses `Vue.set()` for reactivity
`RGDataProvider4Vue3`	Vue 3	Uses `ref()` and `reactive()`
`RGDataProvider4React`	React	Uses state hooks and `setState`
`RGDataProvider4Svelte`	Svelte	Uses writable stores

The data provider abstracts differences in how each framework tracks changes to objects and arrays, allowing the core to remain framework-agnostic while still triggering UI updates appropriately.

Setup Methods:

API Surface

The RelationGraphInstance (alias for RelationGraphCore) exposes methods organized by capability:

Data Operations

Add: addNode(), addNodes(), addLine(), addLines()
Remove: removeNode(), removeNodeById(), removeLine(), removeLineById()
Update: updateNode(), updateLine(), updateNodeData(), updateLineData()
Query: getNodeById(), getLineById(), getNodes(), getLines(), getLinks()

Graph Analysis

Relationships: getRelatedLinesByNode(), getNodeRelatedNodes(), getNodeIncomingNodes()
Network analysis: getNetworkNodesByNode(), getDescendantNodes()
Spatial queries: getNodesRectBox(), getNodesCenter(), getNodesInSelectionView()

Layout Control

Trigger: doLayout(), refresh(), resetViewSize()
Animation: zoomToFit(), focusOnNode(), focusOnLink()

Interaction

Editing mode: startEditingNodes(), startEditingLine(), stopEditingNodes()
Creation: startCreatingNodePlot(), startCreatingLinePlot()
Navigation: setZoom(), zoomIn(), zoomOut(), moveCanvasTo()

Complete API reference: API Reference

Performance Considerations

The system includes multiple optimizations for handling large graphs:

Viewport Culling: Only nodes and lines within the visible viewport are rendered when performanceMode is enabled
EasyView Mode: Automatic fallback to Canvas 2D rendering at low zoom levels (< 40%)
Batched Updates: requestAnimationFrame-based update batching prevents redundant renders
Lazy Calculation: Line paths are only calculated for visible lines
MiniView Optimization: Overview map uses simplified canvas rendering

For details on performance modes: Performance Mode & EasyView

File Structure Overview

relation-graph-vip/
├── packages/
│   ├── types.ts                           # Core type definitions
│   └── relation-graph-models/
│       ├── models/
│       │   ├── RelationGraphBase.ts       # Base class with events
│       │   ├── RelationGraphWith*.ts      # Progressive enhancement classes
│       │   └── RelationGraphCore.ts       # Final assembled class
│       ├── layouters/
│       │   ├── RGForceLayout.ts          # Force-directed algorithm
│       │   ├── RGTreeLayout.ts           # Tree layout
│       │   └── ...                        # Other layout implementations
│       ├── data/
│       │   ├── RGNodeDataUtils.ts        # Node data transformations
│       │   └── RGLineDataUtils.ts        # Line data transformations
│       └── utils/
│           └── line/RGLinePath.ts        # Line path generation
├── platforms/
│   ├── vue2/                              # Vue 2 wrapper package
│   ├── vue3/                              # Vue 3 wrapper package
│   ├── react/                             # React wrapper package
│   ├── svelte/                            # Svelte wrapper package
│   └── web-components/                    # Web Components package
└── package.json                           # Monorepo root

Each platform package contains:

src/components/: Framework-specific UI components
src/core4react/ (or similar): Data provider implementation
package.json: Package metadata and dependencies

Getting Started

To use relation-graph in your project:

Install the appropriate package for your framework
Import the main component and types
Create a graph instance through the component
Set initial data using setJsonData() or addNodes()/addLines()
Configure layout and interaction options
Customize node/line rendering through slots/render props

For detailed setup instructions: Getting Started

For platform-specific integration details: