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

> Discover how Understand-Anything uses ELK and force-directed algorithms for dashboard layout computation. Explore hierarchical views and knowledge graphs with Lum1104/Understand-Anything.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: deep-dive
- Published: 2026-06-06

---

**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`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/src/utils/layout.ts)** (lines 195-203). These options specify a top-down Sugiyama-style layout with orthogonal edge routing:

```typescript
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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/src/utils/layout.ts)** constructs a physics simulation combining multiple forces:

```typescript
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`](https://github.com/Lum1104/Understand-Anything/blob/main/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

```typescript
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`](https://github.com/Lum1104/Understand-Anything/blob/main/layout.ts) lines 95-108; `applyElkLayout` in [`elk-layout.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/elk-layout.ts) lines 225-233.*

### Implementing Force-Directed Layout for Knowledge Graphs

```typescript
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`](https://github.com/Lum1104/Understand-Anything/blob/main/layout.ts) lines 94-100.*

### Deprecated Dagre Fallback

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

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

```

*Source: `applyDagreLayout` in [`layout.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/layout.ts) and executed via `applyElkLayout` in [`elk-layout.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/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`](https://github.com/Lum1104/Understand-Anything/blob/main/packages/dashboard/src/utils/elk-layout.ts)**. The Vite configuration in [`vite.config.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/vite.config.ts) treats `elkjs` as an external dependency to enable WebAssembly loading.