@memberjunction/ng-entity-relationship-diagram

Angular components for rendering interactive Entity Relationship Diagrams (ERD) using D3.js force-directed graphs, with both a MemberJunction-specific wrapper and a generic reusable component.

Overview

This package provides two complementary components for visualizing entity relationships:

1. <mj-entity-erd> — A higher-level wrapper that accepts MemberJunction EntityInfo[] directly, handles automatic relationship discovery, and supports configurable depth traversal.
2. <mj-erd-diagram> — A generic, lower-level component that works with plain ERDNode[] data, suitable for any project regardless of MemberJunction usage.

flowchart LR
    subgraph MJWrapper["mj-entity-erd"]
        EI[EntityInfo Array] --> TRANSFORM[Transform & Discover]
        TRANSFORM --> NODES[ERDNode + ERDLink]
    end

    subgraph Generic["mj-erd-diagram"]
        NODES --> D3[D3.js Force Simulation]
        D3 --> SVG[Interactive SVG]
        SVG --> EVENTS[Selection / Zoom / Drag Events]
    end

    subgraph Features["Capabilities"]
        FOCUS[Focus Mode]
        STATE[State Persistence]
        EXPORT[SVG Export]
    end

    SVG --> Features

    style MJWrapper fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Generic fill:#7c5295,stroke:#563a6b,color:#fff
    style Features fill:#2d8659,stroke:#1a5c3a,color:#fff

Installation

npm install @memberjunction/ng-entity-relationship-diagram

Which Component Should I Use?

Use Case	Component	Why
MemberJunction project	<mj-entity-erd>	Auto-discovers relationships, handles transformation
Custom data sources	<mj-erd-diagram>	Full control over node/link data
Single entity + related	<mj-entity-erd>	Built-in depth/relationship discovery
Non-MJ Angular project	<mj-erd-diagram>	No MJ dependencies in your code

Usage

Import the Module

import { EntityRelationshipDiagramModule } from '@memberjunction/ng-entity-relationship-diagram';

@NgModule({
  imports: [EntityRelationshipDiagramModule]
})
export class YourModule { }

MemberJunction Entity Wrapper

import { EntityInfo, Metadata } from '@memberjunction/core';

@Component({
  selector: 'my-entity-viewer',
  template: `
    <mj-entity-erd
      [entities]="selectedEntities"
      [allEntities]="allEntities"
      [selectedEntityId]="currentEntityId"
      [depth]="1"
      [includeIncoming]="true"
      [includeOutgoing]="true"
      (entitySelected)="onEntitySelected($event)"
      (openRecord)="onOpenEntity($event)">
    </mj-entity-erd>
  `
})
export class MyEntityViewerComponent {
  allEntities: EntityInfo[] = [];
  selectedEntities: EntityInfo[] = [];
  currentEntityId: string | null = null;

  constructor() {
    const md = new Metadata();
    this.allEntities = md.Entities;
  }

  onEntitySelected(entity: EntityInfo) {
    this.currentEntityId = entity.ID;
  }

  onOpenEntity(entity: EntityInfo) {
    // Navigate to entity record
  }
}

Generic ERD Component

import { ERDNode, ERDNodeClickEvent } from '@memberjunction/ng-entity-relationship-diagram';

@Component({
  selector: 'my-schema-viewer',
  template: `
    <mj-erd-diagram
      [nodes]="entityNodes"
      [selectedNodeId]="selectedId"
      (nodeSelected)="onNodeSelected($event)"
      (nodeDoubleClick)="onNodeDoubleClick($event)">
    </mj-erd-diagram>
  `
})
export class SchemaViewerComponent {
  entityNodes: ERDNode[] = [
    {
      id: 'users',
      name: 'Users',
      fields: [
        { id: 'id', name: 'ID', isPrimaryKey: true, type: 'uuid' },
        { id: 'email', name: 'Email', isPrimaryKey: false, type: 'string' },
        { id: 'roleId', name: 'RoleID', isPrimaryKey: false, relatedNodeId: 'roles', relatedFieldName: 'ID' }
      ]
    },
    {
      id: 'roles',
      name: 'Roles',
      fields: [
        { id: 'id', name: 'ID', isPrimaryKey: true, type: 'uuid' },
        { id: 'name', name: 'Name', isPrimaryKey: false, type: 'string' }
      ]
    }
  ];
  selectedId: string | null = null;

  onNodeSelected(node: ERDNode) {
    this.selectedId = node.id;
  }
}

Focus Mode

Show a single entity with its N-hop related entities:

<mj-erd-diagram
  [nodes]="allNodes"
  [focusNodeId]="'users'"
  [focusDepth]="1"
  (nodeSelected)="onNodeSelected($event)">
</mj-erd-diagram>

Depth	Description
0	Show only the focus node
1	Focus node + directly related nodes
2	Focus node + nodes within 2 relationship hops
3+	Continue expanding the relationship graph

API Reference

<mj-entity-erd> Inputs

Input	Type	Default	Description
entities	EntityInfo[]	[]	Primary entities to display
allEntities	EntityInfo[]	[]	All entities for relationship discovery
selectedEntityId	string | null	null	ID of currently selected entity
depth	number	1	Relationship hops to include
includeIncoming	boolean	true	Include entities referencing primary entities
includeOutgoing	boolean	true	Include entities referenced by primary entities
showHeader	boolean	true	Show header with zoom controls
headerTitle	string	'Entity Relationship Diagram'	Header title
isRefreshing	boolean	false	Show loading overlay
readOnly	boolean	false	Disable interactions
config	ERDConfig	{}	Configuration options

<mj-entity-erd> Outputs

Output	Type	Description
entitySelected	EntityInfo	Entity was selected
entityDeselected	void	Selection was cleared
openRecord	EntityInfo	Entity double-clicked
stateChange	ERDState	Diagram state changed

<mj-erd-diagram> Inputs

Input	Type	Default	Description
nodes	ERDNode[]	[]	Nodes (entities) to display
selectedNodeId	string | null	null	Currently selected node
highlightedNodeIds	string[]	[]	Highlighted node IDs
focusNodeId	string | null	null	Focus mode target
focusDepth	number	1	Relationship hops in focus mode
isRefreshing	boolean	false	Show loading overlay
readOnly	boolean	false	Disable dragging and selection
config	ERDConfig	{}	Configuration options
showHeader	boolean	true	Show header with controls
headerTitle	string	'Entity Relationship Diagram'	Title in header

<mj-erd-diagram> Outputs

Selection Events:

Output	Type	Description
nodeClick	ERDNodeClickEvent	Node clicked (cancelable)
nodeDoubleClick	ERDNodeDoubleClickEvent	Node double-clicked
nodeSelected	ERDNode	Node selected
nodeDeselected	void	Selection cleared
linkClick	ERDLinkClickEvent	Relationship link clicked

Hover Events:

Output	Type	Description
nodeHover	ERDNodeHoverEvent	Mouse entered a node
nodeHoverEnd	ERDNode	Mouse left a node
linkHover	ERDLinkHoverEvent	Mouse entered a link
linkHoverEnd	ERDLink	Mouse left a link

Context Menu Events:

Output	Type	Description
nodeContextMenu	ERDNodeContextMenuEvent	Right-click on node
linkContextMenu	ERDLinkContextMenuEvent	Right-click on link
diagramContextMenu	ERDDiagramContextMenuEvent	Right-click on background

Diagram Events:

Output	Type	Description
nodeDragStart	ERDNodeDragEvent	Drag started (cancelable)
nodeDragEnd	ERDNodeDragEvent	Drag ended
zoomChange	ERDZoomEvent	Zoom level or pan changed
refreshRequested	void	Refresh button clicked
layoutComplete	void	Force simulation completed
stateChange	ERDState	Any state change

Public Methods

Access via @ViewChild(ERDDiagramComponent):

// Zoom control
zoomIn(): void
zoomOut(): void
resetZoom(): void
zoomToNode(nodeId: string, scale?: number): void
zoomToFit(padding?: number): void
centerDiagram(): void

// Selection
selectNode(nodeId: string): boolean
deselectAll(): void

// Highlighting
highlightNode(nodeId: string): void
clearHighlights(): void
highlightRelated(nodeId: string, depth?: number): void
getRelatedNodes(nodeId: string, depth?: number): ERDRelationshipInfo[]

// State management
getState(): ERDState
setState(state: Partial<ERDState>, restorePositions?: boolean): void

// Layout control
freezeLayout(): void
unfreezeLayout(): void

// Utilities
refresh(): void
triggerResize(): void
getZoomState(): ERDZoomEvent
exportAsSVG(): string

Configuration

const config: ERDConfig = {
  // Node sizing
  nodeWidth: 180,
  nodeBaseHeight: 60,
  fieldHeight: 20,
  maxNodeHeight: 300,

  // Force simulation
  chargeStrength: -800,
  linkDistance: 80,
  collisionPadding: 20,

  // Display
  showFieldDetails: true,
  showRelationshipLabels: true,
  showHeader: true,
  showNodeCount: true,
  showMinimap: false,
  showLegend: false,

  // Interaction
  enableDragging: true,
  enableZoom: true,
  enablePan: true,
  minZoom: 0.1,
  maxZoom: 4,
  initialZoom: 1,
  enableMultiSelect: false,

  // Animation
  animationDuration: 750,
  fitOnLoad: true,

  // Layout
  layoutAlgorithm: 'force', // 'force' | 'horizontal' | 'vertical' | 'radial'

  // Colors
  colors: {
    nodeBackground: '#f8f9fa',
    nodeBorder: '#333',
    nodeHeader: '#007bff',
    nodeHeaderText: 'white',
    primaryKeyBackground: '#fff3cd',
    foreignKeyBackground: '#cce5ff',
    linkColor: '#666',
    selectedBorder: '#4CAF50',
    highlightBorder: '#ff9800',
    relatedBorder: '#ff6b35'
  }
};

Data Interfaces

interface ERDNode {
  id: string;
  name: string;
  schemaName?: string;
  description?: string;
  status?: string;
  baseTable?: string;
  fields: ERDField[];
  customData?: Record<string, unknown>;
}

interface ERDField {
  id: string;
  name: string;
  type?: string;
  isPrimaryKey: boolean;
  relatedNodeId?: string;
  relatedNodeName?: string;
  relatedFieldName?: string;
  description?: string;
  allowsNull?: boolean;
  defaultValue?: string;
  length?: number;
  isVirtual?: boolean;
  autoIncrement?: boolean;
  customData?: Record<string, unknown>;
}

interface ERDLink {
  sourceNodeId: string;
  targetNodeId: string;
  sourceField: ERDField;
  targetField?: ERDField;
  isSelfReference: boolean;
  relationshipType?: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
  label?: string;
}

interface ERDState {
  selectedNodeId: string | null;
  highlightedNodeIds: string[];
  zoomLevel: number;
  translateX: number;
  translateY: number;
  focusNodeId: string | null;
  focusDepth: number;
  nodePositions: Record<string, { x: number; y: number; fx?: number | null; fy?: number | null }>;
}

Utility Functions

The package exports utility functions for transforming MemberJunction entities to ERD data:

import {
  buildERDDataFromEntities,
  entityInfoToERDNode,
  entityFieldToERDField,
  entitiesToERDNodes,
  getOriginalEntityFromERDNode,
  findEntityByNodeId
} from '@memberjunction/ng-entity-relationship-diagram';

// Build complete ERD data with automatic relationship discovery
const { nodes, links } = buildERDDataFromEntities(primaryEntities, {
  allEntities: md.Entities,
  includeIncoming: true,
  includeOutgoing: true,
  depth: 2
});

State Persistence

// Save diagram state
const state = this.erdDiagram.getState();
localStorage.setItem('erd-state', JSON.stringify(state));

// Restore state on init
ngAfterViewInit() {
  const savedState = localStorage.getItem('erd-state');
  if (savedState) {
    this.erdDiagram.setState(JSON.parse(savedState));
  }
}

Performance Considerations

• For 100+ node diagrams, use focus mode to show subsets
• Call freezeLayout() after the initial layout settles for static diagrams
• Adjust chargeStrength and linkDistance for different node densities
• Set fitOnLoad: false when restoring state to avoid double-animation

Dependencies

Package	Description
@memberjunction/core	Core framework (for entity wrapper)
d3	D3.js force-directed graph engine
@dagrejs/dagre	DAG layout algorithms
@progress/kendo-angular-layout	Layout components
rxjs	Reactive extensions

Peer Dependencies

• @angular/common ^21.x
• @angular/core ^21.x
• @angular/platform-browser ^21.x

Build

cd packages/Angular/Generic/entity-relationship-diagram
npm run build

License

ISC