# bcakmakoglu/vue-flow architecture

> Architecture diagram of the GitHub repository bcakmakoglu/vue-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bcakmakoglu/vue-flow
- Repository: https://github.com/bcakmakoglu/vue-flow

## Overview

1. **What this repo is**
   - This is a **pnpm monorepo** for **Vue Flow**, a Vue 3 flowchart/graph library.
   - The repo is split into a **core rendering/runtime package**, several **optional UI add-on packages**, a **VitePress docs site**, many **example apps**, and **Cypress component tests**.

2. **Core runtime is the center of the architecture**
   - `packages/core` is the primary subsystem and contains the actual graph engine.
   - It owns the **flow store**, **render containers**, **composables**, **types**, and **utility logic** for nodes, edges, handles, selection, zoom/pan, and viewport control.
   - Most other packages are thin extensions that depend on `core` rather than duplicating graph state.

3. **Main data model: nodes, edges, and flow state**
   - The core API revolves around **nodes** and **edges** as graph elements.
   - Nodes carry position and node-specific metadata; edges connect source/target node ids and may also carry custom rendering data.
   - The store layer in `packages/core/src/store` is the central mutable/reactive state boundary; actions, getters, and hooks provide controlled access to that state.

4. **Rendering pipeline**
   - `VueFlow` is the top-level container in `packages/core/src/container/VueFlow`.
   - Inside it, the graph is rendered through layered containers:
     - **Viewport**: pan/zoom transform handling
     - **Pane**: interaction surface and pointer handling
     - **NodeRenderer**: node instances
     - **EdgeRenderer**: edge instances and marker definitions
   - This makes the render path mostly: **props/store → derived state → node/edge renderers → DOM/SVG output**.

5. **Interaction and editing flow**
   - User interactions such as dragging, connecting, selecting, resizing, and keyboard actions are handled through core composables like `useDrag`, `useConnection`, `useNode`, `useEdge`, `useResizeHandler`, and `useKeyPress`.
   - These composables translate pointer/keyboard events into store updates and graph changes.
   - Selection, connection, and viewport behavior are therefore managed as **interaction helpers around the central store**, not as isolated UI logic.

6. **Component boundaries inside core**
   - `packages/core/src/components` contains reusable graph primitives such as:
     - node wrappers and default/input/output node types
     - edge variants and base edge geometry/rendering
     - handle and selection helpers
     - accessibility descriptions and user-selection overlays
   - `packages/core/src/utils` contains graph math and behavioral helpers, including edge path generation, node/handle utilities, storage, logging, and auto-pan logic.

7. **Public API boundary**
   - `packages/core/src/index.ts` and the package entrypoints expose the library surface used by apps and extensions.
   - The repo also includes many composables exported for advanced use, so consumers can either use the high-level `<VueFlow />` component or compose lower-level hooks for custom graph behaviors.
   - The architecture is intentionally split between **simple declarative usage** and **advanced composable-driven control**.

8. **Optional add-on packages**
   - Several sibling packages extend the core without changing it:
     - `packages/background`: background grid/pattern rendering
     - `packages/controls`: zoom/pan control buttons
     - `packages/minimap`: compact overview of the graph
     - `packages/node-resizer`: resize handles and resize controls
     - `packages/node-toolbar`: floating toolbar anchored to nodes
   - These packages typically consume Vue Flow context/state and render in the same flow surface, but remain separate installable artifacts.

9. **Specialized edge package**
   - `packages/pathfinding-edge` is a distinct extension focused on **obstacle-aware edge routing**.
   - It includes grid creation, bounding-box analysis, path generation, SVG path drawing, and arrow rendering.
   - Architecturally, it sits beside the core as a **custom edge implementation package** rather than part of the generic edge renderer.

10. **Documentation site**
   - `docs` is a standalone **VitePress** application that documents the library and showcases behavior.
   - It contains guide pages, API docs, and rich interactive examples implemented in Vue components.
   - The docs site is both a documentation layer and a live integration showcase for the library packages.

11. **Example applications**
   - `examples/` contains full apps for different host frameworks/runtimes: **Vite**, **Nuxt 3**, and **Quasar**.
   - These examples demonstrate how the library integrates into real applications and how custom nodes, edges, layouts, DnD, teleportation, validation, and state persistence are built on top of the core.
   - They are not part of the runtime library itself, but they are important for understanding intended usage boundaries.

12. **Testing and verification**
   - `tests/` uses **Cypress component testing** to validate store behavior, Vue Flow interactions, and optional components.
   - There are explicit test groups for store operations, node/edge updates, viewport behavior, and add-on packages like background, controls, and minimap.
   - This suggests the repo treats graph behavior as a UI/runtime contract that must be tested at the component level.

13. **Build, release, and repo tooling**
   - The repo uses **pnpm workspaces**, **Turbo**, TypeScript project configs, and per-package Vite builds.
   - Release management is changeset-based (`.changeset`, `CHANGELOG.md`, GitHub publish workflow), which is important for diagramming package lifecycle.
   - GitHub Actions handles build/test/publish automation, while the devcontainer supports a reproducible development environment.

14. **How to draw the architecture**
   - The central box should be `packages/core`, with arrows from apps/docs/examples/tests into it.
   - Add-on packages should be shown as **dependents of core** that render into the same flow surface through shared context/store.
   - Docs and examples should be shown as **consumers of the library**, not peers of runtime logic.
   - The main internal flow is: **input nodes/edges → reactive store → render containers/components → user interaction events → store updates → rerender**.

Main entry points: [`packages/core/src/store`](https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/store) (Store), [`packages/core/src/container/VueFlow/VueFlow.vue`](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/VueFlow/VueFlow.vue) (Vue Flow), [`docs/src/.vitepress/config.mts`](https://github.com/bcakmakoglu/vue-flow/blob/master/docs/src/.vitepress/config.mts) (Docs site), [`tests/cypress/component`](https://github.com/bcakmakoglu/vue-flow/tree/master/tests/cypress/component) (Cypress tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_packages_core_vueflow["Vue Flow<br/>entry container<br/>[VueFlow.vue]"]
  node_packages_core_store[("Store<br/>reactive state")]
  node_packages_core_node_renderer["Node renderer<br/>render layer<br/>[NodeRenderer.vue]"]
  node_packages_core_edge_renderer["Edge renderer<br/>render layer<br/>[EdgeRenderer.vue]"]
  node_packages_core_viewport["Viewport<br/>transform layer<br/>[Viewport.vue]"]
  node_packages_core_pane["Pane<br/>interaction surface<br/>[Pane.vue]"]
  node_packages_core_composables["Composables<br/>interaction hooks"]
  node_packages_core_components["Primitives<br/>graph components"]
  node_packages_core_utils["Graph utils<br/>math/behavior helpers"]
  node_packages_core_types["Types<br/>public model"]
end

subgraph group_addons["Add-ons"]
  node_packages_background["Background<br/>surface addon<br/>[Background.vue]"]
  node_packages_controls["Controls<br/>surface addon<br/>[Controls.vue]"]
  node_packages_minimap["Minimap<br/>surface addon<br/>[MiniMap.vue]"]
  node_packages_node_resizer["Node resizer<br/>surface addon<br/>[NodeResizer.vue]"]
  node_packages_node_toolbar["Node toolbar<br/>surface addon<br/>[NodeToolbar.vue]"]
  node_packages_pathfinding_edge["Pathfinding edge<br/>custom edge"]
end

subgraph group_consumers["Consumers"]
  node_docs_site["Docs site<br/>VitePress app<br/>[config.mts]"]
  node_examples_vite["Vite examples<br/>example app<br/>[main.ts]"]
  node_examples_nuxt3["Nuxt example<br/>example app<br/>[app.vue]"]
  node_examples_quasar["Quasar example<br/>example app<br/>[App.vue]"]
end

subgraph group_quality["Quality"]
  node_tests_cypress["Cypress tests<br/>component tests"]
  node_repo_tooling["Tooling<br/>[turbo.json]"]
end

node_packages_core_vueflow -->|"reads/writes"| node_packages_core_store
node_packages_core_vueflow -->|"wraps"| node_packages_core_viewport
node_packages_core_vueflow -->|"hosts"| node_packages_core_pane
node_packages_core_viewport -->|"contains"| node_packages_core_node_renderer
node_packages_core_viewport -->|"contains"| node_packages_core_edge_renderer
node_packages_core_pane -->|"drives"| node_packages_core_composables
node_packages_core_composables -->|"updates"| node_packages_core_store
node_packages_core_store -->|"derives state for"| node_packages_core_node_renderer
node_packages_core_store -->|"derives state for"| node_packages_core_edge_renderer
node_packages_core_store -->|"feeds"| node_packages_core_components
node_packages_core_components -->|"uses"| node_packages_core_utils
node_packages_core_utils -->|"shapes"| node_packages_core_types
node_packages_background -->|"consumes"| node_packages_core_store
node_packages_controls -->|"uses"| node_packages_core_composables
node_packages_minimap -->|"consumes"| node_packages_core_store
node_packages_node_resizer -->|"uses"| node_packages_core_composables
node_packages_node_toolbar -->|"anchors to"| node_packages_core_store
node_packages_pathfinding_edge -->|"extends"| node_packages_core_components
node_docs_site -->|"documents"| node_packages_core_vueflow
node_docs_site -->|"shows"| node_packages_background
node_docs_site -->|"shows"| node_packages_controls
node_docs_site -->|"shows"| node_packages_minimap
node_docs_site -->|"shows"| node_packages_node_resizer
node_docs_site -->|"shows"| node_packages_node_toolbar
node_examples_vite -->|"integrates"| node_packages_core_vueflow
node_examples_vite -->|"demonstrates"| node_packages_node_resizer
node_examples_vite -->|"demonstrates"| node_packages_pathfinding_edge
node_examples_nuxt3 -->|"integrates"| node_packages_core_vueflow
node_examples_quasar -->|"integrates"| node_packages_core_vueflow
node_tests_cypress -->|"verifies"| node_packages_core_store
node_tests_cypress -->|"verifies"| node_packages_core_vueflow
node_tests_cypress -->|"verifies"| node_packages_background
node_tests_cypress -->|"verifies"| node_packages_controls
node_tests_cypress -->|"verifies"| node_packages_minimap
node_repo_tooling -->|"builds"| node_packages_core_vueflow
node_repo_tooling -->|"builds"| node_docs_site
node_repo_tooling -->|"runs"| node_tests_cypress

click node_packages_core_vueflow "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/VueFlow/VueFlow.vue"
click node_packages_core_store "https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/store"
click node_packages_core_node_renderer "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/NodeRenderer/NodeRenderer.vue"
click node_packages_core_edge_renderer "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/EdgeRenderer/EdgeRenderer.vue"
click node_packages_core_viewport "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/Viewport/Viewport.vue"
click node_packages_core_pane "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/Pane/Pane.vue"
click node_packages_core_composables "https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/composables"
click node_packages_core_components "https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/components"
click node_packages_core_utils "https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/utils"
click node_packages_core_types "https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/types"
click node_packages_background "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/background/src/Background.vue"
click node_packages_controls "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/controls/src/Controls.vue"
click node_packages_minimap "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/minimap/src/MiniMap.vue"
click node_packages_node_resizer "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/node-resizer/src/NodeResizer.vue"
click node_packages_node_toolbar "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/node-toolbar/src/NodeToolbar.vue"
click node_packages_pathfinding_edge "https://github.com/bcakmakoglu/vue-flow/blob/master/packages/pathfinding-edge/src/edge/PathFindingEdge.vue"
click node_docs_site "https://github.com/bcakmakoglu/vue-flow/blob/master/docs/src/.vitepress/config.mts"
click node_examples_vite "https://github.com/bcakmakoglu/vue-flow/blob/master/examples/vite/main.ts"
click node_examples_nuxt3 "https://github.com/bcakmakoglu/vue-flow/blob/master/examples/nuxt3/app.vue"
click node_examples_quasar "https://github.com/bcakmakoglu/vue-flow/blob/master/examples/quasar/src/App.vue"
click node_tests_cypress "https://github.com/bcakmakoglu/vue-flow/tree/master/tests/cypress/component"
click node_repo_tooling "https://github.com/bcakmakoglu/vue-flow/blob/master/turbo.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_packages_core_vueflow,node_packages_core_store,node_packages_core_node_renderer,node_packages_core_edge_renderer,node_packages_core_viewport,node_packages_core_pane,node_packages_core_composables,node_packages_core_components,node_packages_core_utils,node_packages_core_types toneBlue
class node_packages_background,node_packages_controls,node_packages_minimap,node_packages_node_resizer,node_packages_node_toolbar,node_packages_pathfinding_edge toneAmber
class node_docs_site,node_examples_vite,node_examples_nuxt3,node_examples_quasar toneMint
class node_tests_cypress,node_repo_tooling toneRose
```

## Components

### Core runtime

Primary graph engine, render pipeline, composables, store, and shared types.

- [Vue Flow](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/VueFlow/VueFlow.vue): entry container · Top-level component and render entry for the core library. · `packages/core/src/container/VueFlow/VueFlow.vue`
- [Store](https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/store): reactive state · Central mutable graph state boundary for nodes, edges, viewport, and selection. · `packages/core/src/store`
- [Node renderer](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/NodeRenderer/NodeRenderer.vue): render layer · Renders node instances from store-derived state. · `packages/core/src/container/NodeRenderer/NodeRenderer.vue`
- [Edge renderer](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/EdgeRenderer/EdgeRenderer.vue): render layer · Renders edges and marker definitions from store-derived state. · `packages/core/src/container/EdgeRenderer/EdgeRenderer.vue`
- [Viewport](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/Viewport/Viewport.vue): transform layer · Handles pan/zoom transforms and viewport framing. · `packages/core/src/container/Viewport/Viewport.vue`
- [Pane](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/core/src/container/Pane/Pane.vue): interaction surface · Pointer and interaction surface for graph editing gestures. · `packages/core/src/container/Pane/Pane.vue`
- [Composables](https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/composables): interaction hooks · Drag, connect, resize, keyboard, and viewport helpers that translate input into store updates. · `packages/core/src/composables`
- [Primitives](https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/components): graph components · Core node, edge, handle, selection, and accessibility primitives. · `packages/core/src/components`
- [Graph utils](https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/utils): math/behavior helpers · Path generation, graph math, node/edge utilities, storage, and autopan helpers. · `packages/core/src/utils`
- [Types](https://github.com/bcakmakoglu/vue-flow/tree/master/packages/core/src/types): public model · Shared node, edge, connection, flow, and store type definitions. · `packages/core/src/types`

### Add-ons

Optional packages that extend the core flow surface.

- [Background](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/background/src/Background.vue): surface addon · Renders grid and pattern backgrounds in the flow surface. · `packages/background/src/Background.vue`
- [Controls](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/controls/src/Controls.vue): surface addon · Zoom and pan control buttons for the flow surface. · `packages/controls/src/Controls.vue`
- [Minimap](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/minimap/src/MiniMap.vue): surface addon · Compact overview of the current graph and viewport. · `packages/minimap/src/MiniMap.vue`
- [Node resizer](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/node-resizer/src/NodeResizer.vue): surface addon · Resize handles and resize controls anchored to nodes. · `packages/node-resizer/src/NodeResizer.vue`
- [Node toolbar](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/node-toolbar/src/NodeToolbar.vue): surface addon · Floating toolbar anchored to selected nodes. · `packages/node-toolbar/src/NodeToolbar.vue`
- [Pathfinding edge](https://github.com/bcakmakoglu/vue-flow/blob/master/packages/pathfinding-edge/src/edge/PathFindingEdge.vue): custom edge · Obstacle-aware routed edge implementation with grid and SVG path generation. · `packages/pathfinding-edge/src/edge/PathFindingEdge.vue`

### Consumers

Docs site and example applications built on top of the library.

- [Docs site](https://github.com/bcakmakoglu/vue-flow/blob/master/docs/src/.vitepress/config.mts): VitePress app · Documentation and live examples for the library. · `docs/src/.vitepress/config.mts`
- [Vite examples](https://github.com/bcakmakoglu/vue-flow/blob/master/examples/vite/main.ts): example app · Primary Vue/Vite showcase app for custom nodes, edges, layouts, and interactions. · `examples/vite/main.ts`
- [Nuxt example](https://github.com/bcakmakoglu/vue-flow/blob/master/examples/nuxt3/app.vue): example app · Nuxt 3 integration example for the library. · `examples/nuxt3/app.vue`
- [Quasar example](https://github.com/bcakmakoglu/vue-flow/blob/master/examples/quasar/src/App.vue): example app · Quasar integration example for the library. · `examples/quasar/src/App.vue`

### Quality

Component tests and repo tooling for build/release workflows.

- [Cypress tests](https://github.com/bcakmakoglu/vue-flow/tree/master/tests/cypress/component): component tests · Component-level verification for store behavior, Vue Flow interactions, and add-ons. · `tests/cypress/component`
- [Tooling](https://github.com/bcakmakoglu/vue-flow/blob/master/turbo.json): workspace tooling · pnpm workspace, Turbo, TypeScript config, changesets, and CI/release automation. · `turbo.json`

## Connections

- Vue Flow → Store: reads/writes · VueFlow is driven by reactive graph state.
- Vue Flow → Viewport: wraps · The top-level container embeds the viewport transform layer.
- Vue Flow → Pane: hosts · The interaction pane captures pointer events over the canvas.
- Viewport → Node renderer: contains · Viewport content includes node rendering.
- Viewport → Edge renderer: contains · Viewport content includes edge rendering.
- Pane → Composables: drives · User gestures are translated through composables.
- Composables → Store: updates · Interaction hooks mutate the central store.
- Store → Node renderer: derives state for · Node renderer consumes store-derived node state.
- Store → Edge renderer: derives state for · Edge renderer consumes store-derived edge state.
- Store → Primitives: feeds · Store state powers primitives like nodes, edges, handles, and selection overlays.
- Primitives → Graph utils: uses · Primitives rely on shared graph and path utilities.
- Graph utils → Types: shapes · Utility functions operate on core graph model types.
- Background → Store: consumes · Add-on reads shared flow state/context.
- Controls → Composables: uses · Controls invoke viewport helpers and state actions.
- Minimap → Store: consumes · Minimap reflects the current graph and viewport.
- Node resizer → Composables: uses · Resize interactions are implemented through core hooks.
- Node toolbar → Store: anchors to · Toolbar positions itself from node state and selection.
- Pathfinding edge → Primitives: extends · Provides a specialized edge implementation beside the generic edge renderer.
- Docs site → Vue Flow: documents · Docs demonstrate the primary runtime API.
- Docs site → Background: shows · Documentation covers add-on components.
- Docs site → Controls: shows · Documentation covers add-on components.
- Docs site → Minimap: shows · Documentation covers add-on components.
- Docs site → Node resizer: shows · Documentation covers add-on components.
- Docs site → Node toolbar: shows · Documentation covers add-on components.
- Vite examples → Vue Flow: integrates · Main example app exercises the core library.
- Vite examples → Node resizer: demonstrates · Examples show optional add-ons and custom behaviors.
- Vite examples → Pathfinding edge: demonstrates · Examples include specialized edge implementations.
- Nuxt example → Vue Flow: integrates · Nuxt example consumes the core library.
- Quasar example → Vue Flow: integrates · Quasar example consumes the core library.
- Cypress tests → Store: verifies · Component tests cover store operations and graph state behavior.
- Cypress tests → Vue Flow: verifies · Component tests cover render and interaction contracts.
- Cypress tests → Background: verifies · Tests cover add-on packages.
- Cypress tests → Controls: verifies · Tests cover add-on packages.
- Cypress tests → Minimap: verifies · Tests cover add-on packages.
- Tooling → Vue Flow: builds · Workspace tooling supports package builds and releases.
- Tooling → Docs site: builds · Workspace tooling supports docs builds.
- Tooling → Cypress tests: runs · Workspace tooling supports component test execution.