Dashboard Layout Computation in Understand-Anything: ELK and Force-Directed Algorithms

The Understand-Anything dashboard computes graph layouts using the ELK layered algorithm for hierarchical structural views and D3-force physics simulation for exploratory knowledge graphs, with a deprecated Dagre fallback for backward compatibility.

The Understand-Anything repository implements sophisticated dashboard layout computation to visualize code architecture and knowledge relationships. The system automatically selects between deterministic hierarchical arrangements and organic force-directed positioning based on the view type, ensuring optimal readability for both rigid structural diagrams and free-form mind maps.

ELK Layered Layout for Hierarchical Views

For structural and hierarchical visualizations such as architecture diagrams and layered dependency graphs, the dashboard employs the ELK (Eclipse Layout Kernel) layered algorithm.

Configuration and Default Options

The ELK layout is configured through ELK_DEFAULT_LAYOUT_OPTIONS defined in packages/dashboard/src/utils/layout.ts (lines 195-203). These options specify a top-down Sugiyama-style layout with orthogonal edge routing:

export const ELK_DEFAULT_LAYOUT_OPTIONS: Record<string, string> = {
  algorithm: "layered",
  "elk.direction": "DOWN",
  "elk.layered.spacing.nodeNodeBetweenLayers": "80",
  "elk.spacing.nodeNode": "60",
  "elk.layered.crossingMinimization.strategy": "LAYER_SWEEP",
  "elk.edgeRouting": "ORTHOGONAL",
  "elk.layered.compaction.postCompaction.strategy": "LEFT",
  "elk.padding": "[top=40,left=20,right=20,bottom=20]",
};

Input Processing and Layout Execution

The applyElkLayout function in packages/dashboard/src/utils/elk-layout.ts orchestrates the layout computation. Before invoking ELK, the repairElkInput function sanitizes the graph data to ensure every node has dimensions, removes duplicate IDs, eliminates orphan children and edges, and breaks containment cycles.

The layout executes in a WebAssembly build of ELK (elkjs/lib/elk.bundled.js), running the layered algorithm that ranks nodes into layers according to edge direction.

Algorithm Steps and Error Handling

The ELK layered algorithm performs three main phases:

1. Ranking — Assigns nodes to hierarchical layers based on the directed edge flow.
2. Ordering — Uses the LAYER_SWEEP strategy to minimize edge crossings within each layer.
3. Compaction — Compresses the layout while maintaining orthogonal edge routing (ORTHOGONAL).

If the layout computation fails, the system catches errors and returns a GraphIssue with the category "elk-layout-failed", allowing the UI to render an empty placeholder instead of crashing.

Force-Directed Layout for Knowledge Graphs

For exploratory knowledge-graph views and mind-map style visualizations, the dashboard uses a force-directed layout implemented with D3-force.

D3-Force Simulation Setup

The applyForceLayout function in packages/dashboard/src/utils/layout.ts constructs a physics simulation combining multiple forces:

const sim = forceSimulation<ForceNode>(simNodes)
  .force("link", forceLink(...).distance(linkDistance).strength(0.2))
  .force("charge", forceManyBody().strength(chargeStrength).distanceMax(1500))
  .force("center", forceCenter(0, 0).strength(0.03))
  .force("collide", forceCollide<ForceNode>().radius(...).strength(0.8));

These forces create link constraints, electrical charge repulsion, gravitational centering, and node collision detection.

Dynamic Scaling and Community Clustering

The implementation automatically scales parameters for graph size. When nodes.length > 100, the system weakens the charge strength (from -350 to -600) and increases link distance (from 150 to 250) to maintain simulation stability.

When a communityMap is provided, the algorithm adds clusterX and clusterY forces that pull nodes toward the center of their respective communities, forming distinct visual clusters. The simulation runs for a deterministic number of ticks calculated as Math.min(300, Math.max(100, nodes.length)) before converging to static coordinates.

Deprecated Dagre Layout

The system retains a synchronous applyDagreLayout function in layout.ts for backward compatibility, though it is marked deprecated and scheduled for removal. This fallback uses the Dagre library's layered algorithm for tiny graphs but has been superseded by ELK for consistency across the dashboard.

Code Implementation Examples

Implementing ELK Layout for Structural Views

import { nodesToElkInput, applyElkLayout } from "./utils/elk-layout";

// Convert XYFlow nodes and edges to ELK input format
const elkInput = nodesToElkInput(nodes, edges, nodeDims);

// Execute layout (async WebAssembly operation)
const { positioned, issues } = await applyElkLayout(elkInput);

// Merge computed positions back to React Flow nodes
const positionedNodes = mergeElkPositions(nodes, positioned);

Source: nodesToElkInput is defined in layout.ts lines 95-108; applyElkLayout in elk-layout.ts lines 225-233.

Implementing Force-Directed Layout for Knowledge Graphs

import { applyForceLayout } from "./utils/layout";

// Apply physics simulation with optional community clustering
const { nodes: positionedNodes, edges: positionedEdges } = applyForceLayout(
  nodes,
  edges,
  nodeDimensions,
  communityMap // Map<string, number> for cluster assignment
);

Source: applyForceLayout defined in layout.ts lines 94-100.

Deprecated Dagre Fallback

import { applyDagreLayout } from "./utils/layout";

// Synchronous layout (deprecated; use ELK instead)
const { nodes, edges } = applyDagreLayout(nodes, edges, "TB");

Source: applyDagreLayout in layout.ts lines 30-38.

Summary

• ELK layered algorithm provides deterministic, hierarchical layouts with orthogonal edge routing for architectural and structural views, configured in layout.ts and executed via applyElkLayout in elk-layout.ts.
• Force-directed layout uses D3-force with scalable parameters and community clustering for organic, exploratory knowledge-graph visualizations via applyForceLayout.
• Dagre layout remains available as a deprecated synchronous fallback but should not be used for new features.
• All algorithms include error handling and automatic parameter scaling to accommodate graphs ranging from tens to hundreds of nodes.

Frequently Asked Questions

What algorithm does Understand-Anything use for hierarchical architecture diagrams?

The dashboard uses the ELK layered algorithm (also known as Sugiyama) for hierarchical views. This algorithm ranks nodes into layers, minimizes edge crossings using the LAYER_SWEEP strategy, and routes edges orthogonally. The implementation resides in packages/dashboard/src/utils/elk-layout.ts.

How does the force-directed layout handle large graphs?

The system detects large graphs (more than 100 nodes) and automatically adjusts physics parameters, weakening the charge strength to -600 and increasing link distance to 250. This prevents the simulation from becoming unstable while maintaining visual clustering through optional community forces.

Can I still use Dagre for dashboard layout computation?

While the applyDagreLayout function still exists in packages/dashboard/src/utils/layout.ts, it is deprecated and scheduled for removal. New implementations should use the ELK layered algorithm for hierarchical layouts or the D3-force implementation for organic layouts.

Where are the layout algorithms configured and maintained?

Central configuration lives in packages/dashboard/src/utils/layout.ts, which exports ELK_DEFAULT_LAYOUT_OPTIONS, applyForceLayout, and applyDagreLayout. ELK-specific execution logic and input repair are handled in packages/dashboard/src/utils/elk-layout.ts. The Vite configuration in vite.config.ts treats elkjs as an external dependency to enable WebAssembly loading.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}