This document provides a high-level overview of maxGraph's multi-layer architecture. It describes the primary components, their responsibilities, and how they interact to enable graph visualization and editing.
For specific topics, see:
maxGraph implements a layered architecture with clear separation of concerns:
Sources:
The Graph class serves as the primary entry point for creating and managing graphs. It extends AbstractGraph and automatically registers default plugins, shapes, edge styles, perimeters, and edge markers.
Key Responsibilities:
Graph: Convenience class that automatically configures all default featuresAbstractGraph: Base implementation providing core graph operations (insertVertex, insertEdge, selection, events)Editor: Higher-level application wrapper that adds actions, undo/redo, keyboard handlers, and UI componentsThe factory pattern is used throughout: Graph provides createCellRenderer(), createGraphDataModel(), createGraphView(), createStylesheet(), and createSelectionModel() methods that can be overridden in subclasses.
Sources:
The data model layer manages the graph structure as a tree of Cell objects, using transactional updates with event notifications.
Key Classes:
GraphDataModel: Manages the cell hierarchy, executes changes transactionally via beginUpdate()/endUpdate(), and fires events for all modifications. Located at packages/core/src/view/GraphDataModel.ts
Cell: Represents vertices, edges, and groups in a tree structure. Each cell has:
id: Unique identifiervalue: User data (typically a label string or XML node)style: Visual properties (CellStyle object)geometry: Position and size informationparent: Parent cell referencechildren[]: Child cell referencessource/target: For edges, references to connected verticesGeometry: Stores position (x, y), size (width, height), control points for edges, and offset. Supports both absolute and relative coordinates.
Transactional Updates:
All model changes must occur within a transaction:
This ensures that view updates and event notifications are batched efficiently.
Sources:
The view layer transforms the data model into visual representations by computing absolute coordinates and creating shape instances.
Key Classes:
GraphView: Coordinates rendering by validating cell states, computing absolute positions, managing scale/translation, and maintaining a cache of CellState objects. Validates the view when the model changes.
CellState: Computed rendering state for a cell, containing:
CellRenderer: Creates and configures Shape instances based on CellState. Determines which shape constructor to use by querying StencilShapeRegistry (custom XML shapes) then ShapeRegistry (built-in shapes).
Shape: Base class for all visual representations. Built-in shapes include RectangleShape, EllipseShape, ConnectorShape, ImageShape, TextShape, etc.
Rendering Pipeline:
GraphView.invalidate()GraphView.validate() is called before renderingCellState with absolute geometry and merged stylesCellRenderer.createShape() instantiates appropriate Shape subclassCellRenderer.configureShape() applies style properties to shapeSources:
The style system uses a cascading merge strategy with registries for shapes, edge styles, perimeters, and edge markers.
Style Resolution Algorithm (from Stylesheet.getCellStyle()):
ignoreDefaultStyle: true)baseStyleNames[] array in orderCellStyle object"none"CellStateStyleExample:
Global Registries:
These registries hold global state and are used during rendering:
ShapeRegistry: Maps shape names to constructor functionsEdgeMarkerRegistry: Maps arrow names ("classic", "block", etc.) to drawing functionsEdgeStyleRegistry: Maps edge style names ("orthogonalEdgeStyle", etc.) to routing functionsPerimeterRegistry: Maps perimeter names ("rectanglePerimeter", etc.) to calculation functionsAll registries are automatically populated when creating a Graph instance via registerDefaultShapes(), registerDefaultEdgeMarkers(), registerDefaultEdgeStyles(), and registerDefaultPerimeters().
Sources:
The plugin system provides modularity for interaction handlers, reducing coupling in the Graph class and enabling tree-shaking.
Plugin Registration:
Plugins are specified during Graph construction:
Plugin Retrieval:
Default Plugins (from getDefaultPlugins()):
The following plugins are included by default:
CellEditorHandler: In-place label editingTooltipHandler: Hover tooltipsSelectionCellsHandler: Selection renderingPopupMenuHandler: Right-click context menuConnectionHandler: Edge creation via dragSelectionHandler: Cell selectionPanningHandler: Pan/zoom navigationCreating Custom Plugins:
Sources:
The serialization layer provides XML export/import for graph models, with support for mxGraph format compatibility.
Key Classes:
Codec: Orchestrates encoding/decoding of object graphs to/from XMLObjectCodec: Generic codec that handles arbitrary objects by introspectionCodecRegistry: Global registry mapping class names to codec instancesModelXmlSerializer: Convenience wrapper that auto-registers model codecs and provides simpler APIUsage Pattern:
mxGraph Compatibility:
ModelXmlSerializer can import XML from mxGraph (with mx-prefixed class names):
This enables interoperability with draw.io/diagrams.net and migration from mxGraph.
Sources:
maxGraph uses several global configuration objects and registries that can be customized:
Global Configuration Objects:
GlobalConfig: i18n settings, logger configurationStyleDefaultsConfig: Default style property valuesStencilShapeConfig: Configuration for XML-based custom shapesEdgeHandlerConfig, VertexHandlerConfig, etc.Reset Functions:
For testing and isolation, configuration can be reset to defaults:
Registries:
All registries support unregistration for custom configurations:
This enables tree-shaking by registering only required features.
Sources:
maxGraph's architecture is organized into distinct, collaborating layers:
Graph (auto-configured) or AbstractGraph (manual configuration)GraphDataModel manages Cell tree with transactional updatesGraphView computes CellState objects; CellRenderer creates Shape instancesStylesheet merges styles; registries provide shapes, edge styles, perimeters, markersGraphPlugin interfaceCodec system with ModelXmlSerializer for XML import/exportThis separation enables:
For deeper exploration of specific components, refer to the detailed pages for each subsystem.