# clientio/joint architecture

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

- Interactive diagram: https://gitdiagram.com/clientio/joint
- Repository: https://github.com/clientio/joint

## Overview

1. This is a Yarn workspaces monorepo for the JointJS ecosystem. The center of gravity is `packages/joint-core`, with companion packages for React integration, reusable shape libraries, layout algorithms, decorators, a CLI utility, and a Vitest SVG mock plugin. The `examples/` directory is a large catalog of standalone apps that consume these packages and serve as reference architectures.

2. `packages/joint-core` is the core diagramming engine. It is SVG-based and MVC-oriented, with the main runtime objects under `src/dia` such as `Graph`, `Paper`, `Cell`, `Element`, `Link`, views, tools, and layer management. This package is the foundation for everything else in the repo.

3. The core rendering and interaction pipeline is: graph model updates in `dia/Graph` and related cell classes, views render onto `dia/Paper`, tools/highlighters modify interaction and appearance, and utilities/geometry helpers support layout, routing, and hit-testing. The core also includes anchoring, connection points, connectors, routers, and layout helpers, which are the main boundaries for diagram behavior customization.

4. `packages/joint-core/src/shapes` and the separate `packages/joint-shapes-general` / `packages/joint-shapes-general-tools` packages provide shape catalogs and shape-specific controls. These are not the rendering engine itself; they are higher-level shape definitions and interactive tools built on top of core primitives.

5. `packages/joint-layout-directed-graph` and `packages/joint-layout-msagl` are standalone layout engines. They consume graph-like input and produce geometry/layout results that JointJS can apply to cells and links. The `examples/layout-*` folders demonstrate these as external algorithm integrations rather than core responsibilities.

6. `packages/joint-react` is the main framework adapter. It bridges React component trees to JointJS `Graph`/`Paper` state through contexts, hooks, data stores, and renderer components. The package is organized around `paper`, `graph-provider`, `measured-node`, `port`, `text-node`, and highlighter components, showing that React is used as a declarative UI layer on top of the imperative diagram engine.

7. The data flow in `joint-react` is: React props/state feed a graph store and paper context, hooks create/update/remove cells, and measured DOM nodes are observed to size elements before JointJS renders them. This package is the boundary where React lifecycle, DOM measurement, and JointJS graph synchronization meet.

8. `packages/joint-decorators` adds TypeScript decorators and parsing helpers for a more declarative way to define JointJS models/views/SVG attributes. It is a small meta-programming layer that sits above core and helps authoring class-based extensions.

9. `packages/joint-cli` is a Node-based utility for listing and downloading examples or resources from GitHub. It is operational tooling, not part of the diagram runtime, and its tests cover GitHub and download behaviors. It indicates the repo has some distribution/support automation beyond the library packages themselves.

10. The `examples/` directory is the primary consumer surface. Most examples are self-contained browser apps built with Vite or Webpack, using plain JavaScript, TypeScript, Angular, or React depending on the example. These demonstrate distinct diagramming concerns such as ports, routing, layouts, custom shapes, drag/drop, and integration patterns.

11. `packages/joint-core/demo` is a second, older/demo-oriented consumer surface for JointJS Core. These demos are largely browser-based HTML/JS assets and show the lower-level API directly. They are useful for understanding raw core boundaries because they bypass framework adapters.

12. Testing and build infrastructure are split by package and runtime. `joint-core` uses a legacy Grunt/Rollup/TypeScript build pipeline with browser, node, and type tests; `joint-react` uses Jest, Storybook, and Vite; layout packages have Karma/Rollup setups; the repo root also has GitHub Actions workflows for CI, publishing docs, CodeQL, and stale issue automation. This matters architecturally because the repo supports both library distribution and documentation/demo publishing.

13. The main architecture boundary is therefore: core diagramming primitives and rendering in `joint-core`, optional higher-level adapters and libraries in sibling packages, and many example applications that demonstrate how to compose those pieces in different UI stacks. An architecture diagram should show `joint-core` at the center, with layout/shape/react/decorator packages as satellites, and examples/tests as consumers around the edge.

Main entry points: [`packages/joint-core`](https://github.com/clientio/joint/tree/master/packages/joint-core) (joint-core), [`packages/joint-react`](https://github.com/clientio/joint/tree/master/packages/joint-react) (joint-react), [`examples`](https://github.com/clientio/joint/tree/master/examples) (examples), [`.github/workflows`](https://github.com/clientio/joint/blob/master/.github/workflows) (workspace CI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Workspace"]
  node_workspace_ci["workspace CI<br/>repo automation<br/>[workflows]"]
end

subgraph group_core["Core engine"]
  node_joint_core[("joint-core<br/>svg diagram engine")]
  node_core_model["Graph model<br/>dia model"]
  node_core_paper["Paper view<br/>dia rendering"]
  node_core_tools["Tools & highlighters<br/>interaction layer"]
  node_core_geometry["Geometry & routing<br/>math/layout utils"]
  node_core_shapes["Built-in shapes<br/>shape catalog"]
end

subgraph group_adapters["Adapters & libraries"]
  node_joint_react[("joint-react<br/>React adapter")]
  node_react_store["Graph store<br/>state sync"]
  node_react_render["Paper UI<br/>React renderer"]
  node_react_hooks["React hooks<br/>cell ops"]
  node_react_widgets["Ports & highlighters<br/>react components"]
  node_joint_shapes_general["shapes-general<br/>shape library"]
  node_joint_shapes_tools["shape tools<br/>shape controls"]
  node_layout_dg["directed-graph layout<br/>layout engine"]
  node_layout_msagl["MSAGL layout<br/>layout engine"]
  node_joint_decorators["joint-decorators<br/>meta layer"]
  node_joint_cli["joint-cli<br/>node utility"]
  node_vitest_svg_mock["svg mock plugin<br/>vitest plugin"]
end

subgraph group_consumers["Consumers"]
  node_examples["examples<br/>sample apps"]
  node_core_demos["core demos<br/>demo surface"]
end

node_joint_core -->|"owns"| node_core_model
node_joint_core -->|"renders"| node_core_paper
node_joint_core -->|"exposes"| node_core_tools
node_joint_core -->|"computes"| node_core_geometry
node_joint_core -->|"bundles"| node_core_shapes
node_joint_react -->|"syncs"| node_react_store
node_joint_react -->|"renders"| node_react_render
node_joint_react -->|"orchestrates"| node_react_hooks
node_joint_react -->|"provides"| node_react_widgets
node_joint_shapes_general -->|"extends"| node_joint_core
node_joint_shapes_tools -->|"controls"| node_joint_shapes_general
node_layout_dg -->|"feeds"| node_joint_core
node_layout_msagl -->|"feeds"| node_joint_core
node_joint_decorators -->|"augments"| node_joint_core
node_examples -->|"consumes"| node_joint_core
node_examples -->|"consumes"| node_joint_react
node_examples -->|"demonstrates"| node_layout_dg
node_examples -->|"demonstrates"| node_layout_msagl
node_examples -->|"uses"| node_joint_shapes_general
node_core_demos -->|"exercises"| node_joint_core
node_joint_cli -->|"manages"| node_examples
node_vitest_svg_mock -->|"tests"| node_joint_react
node_workspace_ci -->|"builds"| node_joint_core
node_workspace_ci -->|"builds"| node_joint_react
node_workspace_ci -->|"builds"| node_joint_cli

click node_joint_core "https://github.com/clientio/joint/tree/master/packages/joint-core"
click node_core_model "https://github.com/clientio/joint/tree/master/packages/joint-core/src/dia"
click node_core_paper "https://github.com/clientio/joint/tree/master/packages/joint-core/src/dia"
click node_core_tools "https://github.com/clientio/joint/tree/master/packages/joint-core/src"
click node_core_geometry "https://github.com/clientio/joint/tree/master/packages/joint-core/src"
click node_core_shapes "https://github.com/clientio/joint/tree/master/packages/joint-core/src/shapes"
click node_joint_react "https://github.com/clientio/joint/tree/master/packages/joint-react"
click node_react_store "https://github.com/clientio/joint/tree/master/packages/joint-react/src"
click node_react_render "https://github.com/clientio/joint/tree/master/packages/joint-react/src/components"
click node_react_hooks "https://github.com/clientio/joint/tree/master/packages/joint-react/src/hooks"
click node_react_widgets "https://github.com/clientio/joint/tree/master/packages/joint-react/src/components"
click node_joint_shapes_general "https://github.com/clientio/joint/tree/master/packages/joint-shapes-general"
click node_joint_shapes_tools "https://github.com/clientio/joint/tree/master/packages/joint-shapes-general-tools"
click node_layout_dg "https://github.com/clientio/joint/tree/master/packages/joint-layout-directed-graph"
click node_layout_msagl "https://github.com/clientio/joint/tree/master/packages/joint-layout-msagl"
click node_joint_decorators "https://github.com/clientio/joint/tree/master/packages/joint-decorators"
click node_joint_cli "https://github.com/clientio/joint/tree/master/packages/joint-cli"
click node_vitest_svg_mock "https://github.com/clientio/joint/tree/master/packages/joint-vitest-plugin-mock-svg"
click node_examples "https://github.com/clientio/joint/tree/master/examples"
click node_core_demos "https://github.com/clientio/joint/tree/master/packages/joint-core/demo"
click node_workspace_ci "https://github.com/clientio/joint/blob/master/.github/workflows"

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_workspace_ci toneBlue
class node_joint_core,node_core_model,node_core_paper,node_core_tools,node_core_geometry,node_core_shapes toneAmber
class node_joint_react,node_react_store,node_react_render,node_react_hooks,node_react_widgets,node_joint_shapes_general,node_joint_shapes_tools,node_layout_dg,node_layout_msagl,node_joint_decorators,node_joint_cli,node_vitest_svg_mock toneMint
class node_examples,node_core_demos toneRose
```

## Components

### Workspace

Yarn monorepo and repo-level automation

- [workspace CI](https://github.com/clientio/joint/blob/master/.github/workflows): repo automation · Root-level build, publishing, code scanning, and stale-issue workflows that support the monorepo. · `.github/workflows`

### Core engine

JointJS runtime and its main subsystems

- [joint-core](https://github.com/clientio/joint/tree/master/packages/joint-core): svg diagram engine · Primary JointJS runtime; MVC-based graph model, SVG paper rendering, tools, routing, geometry, shapes, and legacy demos. · `packages/joint-core`
- [Graph model](https://github.com/clientio/joint/tree/master/packages/joint-core/src/dia): dia model · Graph, cell, element, link, layers, and topology/hierarchy state management. · `packages/joint-core/src/dia`
- [Paper view](https://github.com/clientio/joint/tree/master/packages/joint-core/src/dia): dia rendering · Paper, cell/link views, layer views, and SVG rendering/interaction surface. · `packages/joint-core/src/dia`
- [Tools & highlighters](https://github.com/clientio/joint/tree/master/packages/joint-core/src): interaction layer · Cell/link tools and highlighters that modify interaction and appearance. · `packages/joint-core/src`
- [Geometry & routing](https://github.com/clientio/joint/tree/master/packages/joint-core/src): math/layout utils · Geometry primitives plus anchors, connection points, connectors, routers, and layout helpers. · `packages/joint-core/src`
- [Built-in shapes](https://github.com/clientio/joint/tree/master/packages/joint-core/src/shapes): shape catalog · Standard shapes and shape-related exports bundled with the core runtime. · `packages/joint-core/src/shapes`

### Adapters & libraries

Packages layered on top of the core engine

- [joint-react](https://github.com/clientio/joint/tree/master/packages/joint-react): React adapter · Declarative React layer that syncs component trees with JointJS graph and paper state. · `packages/joint-react`
- [Graph store](https://github.com/clientio/joint/tree/master/packages/joint-react/src): state sync · Graph-provider, paper context, and store logic that coordinate JointJS state with React lifecycle. · `packages/joint-react/src`
- [Paper UI](https://github.com/clientio/joint/tree/master/packages/joint-react/src/components): React renderer · Paper component tree, measured-node support, and rendering bridges for SVG/HTML content. · `packages/joint-react/src/components`
- [React hooks](https://github.com/clientio/joint/tree/master/packages/joint-react/src/hooks): cell ops · Hooks for creating, updating, removing, and observing cells plus paper/graph wiring. · `packages/joint-react/src/hooks`
- [Ports & highlighters](https://github.com/clientio/joint/tree/master/packages/joint-react/src/components): react components · Declarative ports, text nodes, and highlighter components exposed to React users. · `packages/joint-react/src/components`
- [shapes-general](https://github.com/clientio/joint/tree/master/packages/joint-shapes-general): shape library · Reusable higher-level shape definitions built on top of joint-core primitives. · `packages/joint-shapes-general`
- [shape tools](https://github.com/clientio/joint/tree/master/packages/joint-shapes-general-tools): shape controls · Interactive controls for the general shape library and shape-specific editing affordances. · `packages/joint-shapes-general-tools`
- [directed-graph layout](https://github.com/clientio/joint/tree/master/packages/joint-layout-directed-graph): layout engine · Standalone directed-graph layout package that computes geometry for JointJS cells and links. · `packages/joint-layout-directed-graph`
- [MSAGL layout](https://github.com/clientio/joint/tree/master/packages/joint-layout-msagl): layout engine · Standalone MSAGL-based layout engine for graph geometry generation. · `packages/joint-layout-msagl`
- [joint-decorators](https://github.com/clientio/joint/tree/master/packages/joint-decorators): meta layer · TypeScript decorators and parsing helpers for declarative JointJS model/view authoring. · `packages/joint-decorators`
- [joint-cli](https://github.com/clientio/joint/tree/master/packages/joint-cli): node utility · CLI for listing and downloading examples/resources from GitHub; operational tooling around the repo. · `packages/joint-cli`
- [svg mock plugin](https://github.com/clientio/joint/tree/master/packages/joint-vitest-plugin-mock-svg): vitest plugin · Vitest SVG mock plugin package with React and Vue test fixtures. · `packages/joint-vitest-plugin-mock-svg`

### Consumers

Example apps and demo surfaces that exercise the libraries

- [examples](https://github.com/clientio/joint/tree/master/examples): sample apps · Large catalog of standalone apps demonstrating ports, routing, layouts, shapes, and framework integrations. · `examples`
- [core demos](https://github.com/clientio/joint/tree/master/packages/joint-core/demo): demo surface · Older JointJS Core demo catalog showing lower-level APIs directly. · `packages/joint-core/demo`

## Connections

- joint-core → Graph model: owns · Core runtime centers on graph and cell state.
- joint-core → Paper view: renders · Model changes are rendered through Paper and views.
- joint-core → Tools & highlighters: exposes · Interaction and appearance are extended via tools and highlighters.
- joint-core → Geometry & routing: computes · Core diagrams depend on geometry, anchors, routers, and connectors.
- joint-core → Built-in shapes: bundles · Standard shapes ship with the core package.
- joint-react → Graph store: syncs · React state is bridged into graph and paper contexts.
- joint-react → Paper UI: renders · Components assemble the paper surface and measured DOM nodes.
- joint-react → React hooks: orchestrates · Hooks create, update, and remove JointJS cells.
- joint-react → Ports & highlighters: provides · Declarative ports, text, and highlighters sit above the core engine.
- shapes-general → joint-core: extends · General shapes are authored on top of core primitives.
- shape tools → shapes-general: controls · Tools customize the reusable shape catalog.
- directed-graph layout → joint-core: feeds · Layout results are applied to JointJS graphs and links.
- MSAGL layout → joint-core: feeds · MSAGL geometry is consumed by JointJS diagrams.
- joint-decorators → joint-core: augments · Decorator helpers sit above core models and views.
- examples → joint-core: consumes · Examples primarily exercise the core engine.
- examples → joint-react: consumes · Some examples demonstrate the React adapter.
- examples → directed-graph layout: demonstrates · Layout examples showcase directed-graph integration.
- examples → MSAGL layout: demonstrates · Layout examples showcase MSAGL integration.
- examples → shapes-general: uses · Example apps consume reusable shape catalogs.
- core demos → joint-core: exercises · Core demos use the low-level API surface directly.
- joint-cli → examples: manages · CLI tooling lists and downloads example resources.
- svg mock plugin → joint-react: tests · The mock plugin package includes React/Vue fixture coverage.
- workspace CI → joint-core: builds · CI covers core build, tests, and publishing tasks.
- workspace CI → joint-react: builds · CI and docs publishing cover the React package.
- workspace CI → joint-cli: builds · CI validates operational tooling as part of the workspace.