clientio/joint

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.