# reaviz/reaflow architecture

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

- Interactive diagram: https://gitdiagram.com/reaviz/reaflow
- Repository: https://github.com/reaviz/reaflow

## Overview

##### Project type and purpose
- It exposes a single high-level API (`<Canvas>` component) to which consumer apps supply graph data (nodes/edges) and custom symbol components.

##### File structure
- Top-level:
- Configuration (.eslintrc, tsconfig.json, .storybook, GitHub workflows)
- `src/` – the library source (core component, layout, helpers, symbols, utils, types)
- `stories/` – Storybook stories showcasing usage examples
- `docs/` – documentation and code sandbox templates
- `test/` & `src/**/*.test.ts` – unit tests
- Key patterns:
- src/layout – integration with ELKJS for automatic graph layout
- src/helpers & src/utils – custom React hooks and utility functions (undo/redo, drag, zoom, selection, proximity)

##### README for additional insights
- Confirms core features: automatic layout, interactions (drag, zoom, pan), nesting, selection, undo/redo, helper abstractions for proximity linking.
- Primary export: `Canvas` – consumes props (nodes, edges, layout, helpers, event callbacks).
- Development uses Storybook for live examples, GitHub Actions for build and npm publish.

a. Main components
- Consumer Application (user’s React app)
- Reaflow Library
· API Layer: `<Canvas>` and exported hooks
· Core Engine: CanvasProvider, GraphRenderer, Contexts
· Layout Module: `elkLayout` (ELKJS wrapper) + `useLayout`
· Helper Hooks: `useZoom`, `useNodeDrag`, `useEdgeDrag`, `useSelection`, `useProximity`, `useUndo`
· Utilities: shared helper functions, types
- External Services/Dependencies
· ELKJS (layout engine)
· React / ReactDOM
· Testing (Jest)
· Storybook
· CI/CD (GitHub Actions → npm registry)

b. Relationships & interactions
- Consumer passes graph data and configuration into `<Canvas>`.
- CanvasProvider initializes context and state (nodes, edges, history stack).
- GraphRenderer invokes layout module (ELKJS) or custom layout, computes node/edge positions.
- Symbol components render based on computed positions.
- Helper hooks listen to user events (drag, click, wheel), update context state, trigger re‐renders or layout recalculations.
- Undo/redo hook wraps state updates.
- External services: CI builds/publishes package; Storybook loads the library in an isolated env.

c. Architectural patterns & design principles
- Modular design: symbols, helpers, layout are pluggable.
- Single Context Provider to share state across components.
- Hook-based abstractions for interactivity.
- Separation of concerns: layout vs. rendering vs. interaction vs. API.
- Extensibility: consumers can supply custom node/edge components or override helpers.

d. Key technologies & frameworks
- React & React Hooks
- TypeScript
- ELKJS for graph layout
- Storybook for interactive docs
- Jest for unit tests
- Vite for bundling

##### Diagramming recommendations
- Use clear labels: “Consumer App,” “Canvas API,” “Layout Module,” “Symbol Components,” “Helper Hooks,” “Context Provider,” “External Services.”
- App → Canvas API → Context → Layout & Render → Browser
- User events → Helper Hooks → Context updates → Re‐render
- Green for external dependencies (ELKJS, React)
- Orange for dev tools (Storybook, CI/CD)
- Related modules visually (e.g., wrap all hooks in a “Helpers” container)

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Consumer Layer"
    App["Consumer App"]:::external
  end

  subgraph "Reaflow Library"
    subgraph "API Layer"
      Canvas["Canvas API"]:::api
    end

    subgraph "Core Engine"
      Provider["CanvasProvider"]:::core
      Renderer["GraphRenderer"]:::core
    end

    subgraph "Layout Module"
      ElkLayout["elkLayout"]:::layout
      UseLayout["useLayout"]:::layout
      LayoutIndex["Layout Index"]:::layout
    end

    subgraph "Symbol Registry"
      SymbolIndex["Symbols Index"]:::symbol
      NodeSym["Node"]:::symbol
      EdgeSym["Edge"]:::symbol
      PortSym["Port"]:::symbol
      LabelSym["Label"]:::symbol
      ArrowSym["Arrow"]:::symbol
      IconSym["Icon"]:::symbol
      AddSym["Add Control"]:::symbol
      RemoveSym["Remove Control"]:::symbol
    end

    subgraph "Helper Hooks"
      UseProx["useProximity"]:::helper
      UseSel["useSelection"]:::helper
      UseUndo["useUndo"]:::helper
      CrudHelpers["CRUD Helpers"]:::helper
    end

    subgraph "Utilities"
      UseZoom["useZoom"]:::util
      UseNodeDrag["useNodeDrag"]:::util
      UseEdgeDrag["useEdgeDrag"]:::util
      HelpersUtil["Shared Helpers"]:::util
    end

    Types["Types"]:::util
  end

  subgraph "External Dependencies"
    React["React / ReactDOM"]:::external
    ELK["ELKJS"]:::external
  end

  subgraph "Dev Tools"
    Storybook["Storybook"]:::dev
    CI["GitHub Actions"]:::dev
  end

  App -->|"renders"| Canvas
  Canvas -->|"provides context"| Provider
  Provider -->|"renders"| Renderer
  Renderer -->|"uses layout"| ElkLayout
  Renderer -->|"calls hook"| UseLayout
  ElkLayout --> ELK
  UseLayout --> ElkLayout
  Renderer -->|"renders symbols"| SymbolIndex
  SymbolIndex --> NodeSym
  SymbolIndex --> EdgeSym
  SymbolIndex --> PortSym
  SymbolIndex --> LabelSym
  SymbolIndex --> ArrowSym
  SymbolIndex --> IconSym
  SymbolIndex --> AddSym
  SymbolIndex --> RemoveSym
  Provider --> UseProx
  Provider --> UseSel
  Provider --> UseUndo
  UseUndo --> CrudHelpers
  Provider --> UseZoom
  Provider --> UseNodeDrag
  Provider --> UseEdgeDrag
  HelpersUtil --> UseZoom
  HelpersUtil --> UseNodeDrag
  HelpersUtil --> UseEdgeDrag
  Canvas --> React
  Storybook --> Canvas
  CI --> Canvas

  click Canvas "https://github.com/reaviz/reaflow/blob/master/src/Canvas.tsx"
  click Provider "https://github.com/reaviz/reaflow/blob/master/src/utils/CanvasProvider.tsx"
  click ElkLayout "https://github.com/reaviz/reaflow/blob/master/src/layout/elkLayout.ts"
  click UseLayout "https://github.com/reaviz/reaflow/blob/master/src/layout/useLayout.ts"
  click LayoutIndex "https://github.com/reaviz/reaflow/blob/master/src/layout/index.ts"
  click SymbolIndex "https://github.com/reaviz/reaflow/blob/master/src/symbols/index.ts"
  click NodeSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Node/Node.tsx"
  click NodeSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Node/index.ts"
  click EdgeSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Edge/Edge.tsx"
  click EdgeSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Edge/index.ts"
  click PortSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Port/Port.tsx"
  click PortSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Port/index.ts"
  click LabelSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Label/Label.tsx"
  click LabelSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Label/index.ts"
  click ArrowSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Arrow/Arrow.tsx"
  click ArrowSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Arrow/index.ts"
  click IconSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Icon/Icon.tsx"
  click IconSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Icon/index.ts"
  click AddSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Add/Add.tsx"
  click AddSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Add/index.ts"
  click RemoveSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Remove/Remove.tsx"
  click RemoveSym "https://github.com/reaviz/reaflow/blob/master/src/symbols/Remove/index.ts"
  click UseProx "https://github.com/reaviz/reaflow/blob/master/src/helpers/useProximity.ts"
  click UseSel "https://github.com/reaviz/reaflow/blob/master/src/helpers/useSelection.ts"
  click UseUndo "https://github.com/reaviz/reaflow/blob/master/src/helpers/useUndo.ts"
  click CrudHelpers "https://github.com/reaviz/reaflow/blob/master/src/helpers/crudHelpers.ts"
  click UseZoom "https://github.com/reaviz/reaflow/blob/master/src/utils/useZoom.ts"
  click UseNodeDrag "https://github.com/reaviz/reaflow/blob/master/src/utils/useNodeDrag.ts"
  click UseEdgeDrag "https://github.com/reaviz/reaflow/blob/master/src/utils/useEdgeDrag.ts"
  click HelpersUtil "https://github.com/reaviz/reaflow/blob/master/src/utils/helpers.ts"
  click HelpersUtil "https://github.com/reaviz/reaflow/blob/master/src/helpers/graphHelpers.ts"
  click Types "https://github.com/reaviz/reaflow/blob/master/src/types.ts"

  classDef api fill:#b3d4fc,stroke:#0366d6,color:#0366d6;
  classDef core fill:#cce5ff,stroke:#004085,color:#004085;
  classDef layout fill:#d4edda,stroke:#155724,color:#155724;
  classDef symbol fill:#fce5cd,stroke:#e36c09,color:#e36c09;
  classDef helper fill:#fff3cd,stroke:#856404,color:#856404;
  classDef util fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
  classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
  classDef dev fill:#f8d7da,stroke:#721c24,color:#721c24;
```
