Skip to content
NgDiagram

Architecture

ngDiagram follows a layered architecture that separates concerns and enables extensibility. This design makes it easy to understand, customize, and extend for your specific needs.

Architecture Flow

Section titled “Architecture Flow”

When a user interacts with the diagram, here’s what happens:

  1. User Interaction: User clicks, drags, or presses keys on diagram components
  2. Event Capture & Processing: User interactions are captured and processed to determine the appropriate action
  3. Command Emission: Based on the event, one or more commands are emitted to represent the intended operation
  4. Middleware Pipeline: Commands flow through middleware chain for validation, transformation, or side effects
  5. Model Update: Final state changes are applied to the model
  6. UI Reactivity: Angular signals automatically update the UI to reflect new state

This unidirectional flow ensures predictable behavior and makes debugging straightforward.

Architecture Layers

Section titled “Architecture Layers”

Components Layer

Section titled “Components Layer”

The user-facing components that render the diagram and handle user interactions:

Service Layer

Section titled “Service Layer”

Specialized services provide different levels of control and functionality:

All services are provided through provideNgDiagram(), allowing multiple diagrams on the same page to maintain their own isolated state and behavior. Learn more in the Services documentation.

Event Layer

Section titled “Event Layer”

The event layer captures user interactions and translates them into commands that modify the diagram state. Events are emitted by the NgDiagramComponent and can be handled via Angular outputs.

Available events:

Each event provides a strongly-typed payload with relevant details. You can subscribe to these events using Angular outputs (e.g. (selectionChanged)="...") on the <ng-diagram> component.

See DiagramEventMap for more information on available events and their payloads.

Command System

Section titled “Command System”

Commands provide precise, structured instructions for state changes in the diagram. After events are processed, handlers emit commands that represent the intended operation:

  • Atomic Operations: Each command represents a single, well-defined action (select, moveNode, addEdge, etc.)
  • Command Emission: Event handlers analyze user interactions and emit appropriate commands through the CommandHandler
  • Transaction Support: Commands can be grouped into transactions for atomic execution, ensuring data consistency
  • Extensible: The system supports 40+ built-in commands and can be extended with custom commands

The command system acts as the bridge between user interactions (events) and state changes (model updates), ensuring all modifications go through a controlled, predictable pipeline.

Middleware System

Section titled “Middleware System”

Middleware intercepts commands before they reach the model, enabling behavior extension without modifying core code:

  • Plugin Architecture: Add, remove, or modify behaviors without changing core code, making the system highly extensible
  • Processing Pipeline: Middleware processes commands and state updates in sequence, allowing for validation, transformation, and side effects
  • Configurable: Each middleware can be enabled/disabled and configured at runtime, providing flexibility
  • Async Support: Middlewares can perform asynchronous operations like API calls or validations

Learn more in the Middlewares documentation.

Data Model

Section titled “Data Model”

The foundation that stores diagram state and provides the data layer:

  • Nodes: Visual elements with position, data, and behavior that represent entities in your diagram. See Nodes documentation for details.
  • Edges: Connections between nodes with routing and styling that represent relationships. See Edges documentation for details.
  • Metadata: Viewport state, middleware configurations, and other settings that control diagram behavior

The default Signal Model uses Angular signals for reactive state management, providing excellent performance and real-time updates. For advanced use cases, custom model adapters can integrate with external data sources like databases or APIs. Learn more in the State Management documentation.