Auto Layout: Organize Your Architecture Diagrams Instantly

There's a task that every architecture team eventually faces: the diagram has grown. What started as five neatly arranged systems is now twenty-seven elements with forty relationships, half of them crossing over each other. Someone added a new container last week and dropped it in the only open space — the bottom-right corner, connected by a line that cuts through three other nodes. The diagram still contains accurate information. It's just unreadable.

So someone spends an afternoon dragging boxes around. They get the top half looking good, then realize moving the API gateway breaks the alignment of everything below it. They start over. An hour later, the diagram is slightly better. The next person to add an element puts it in the wrong spot, and the cycle repeats.

This is a layout problem, and layout problems have algorithmic solutions. That's what Auto Layout does.

One Click, Everything Moves

Auto Layout lives in the diagram toolbar. Click the button, and every element on your diagram — systems, containers, components, code elements, overlays, and compound groups — moves to a computed optimal position. Relationships untangle. Crossing edges separate. The hierarchy becomes visible.

The animation takes 400 milliseconds. Nodes glide from their current positions to their new ones with an eased cubic curve. You see the transformation happen, which helps you maintain spatial orientation — you can track where each element went rather than having the diagram suddenly snap to an unfamiliar arrangement.

How It Works

Under the hood, Auto Layout uses ELK.js, the Eclipse Layout Kernel compiled to JavaScript. ELK is a graph layout engine that implements several decades of research in automatic graph drawing. Archyl uses its layered algorithm, which is specifically designed for directed graphs — exactly what architecture diagrams are.

The layout process runs in several stages:

Layer Assignment

ELK first assigns each node to a layer based on its position in the dependency graph. Elements with no incoming relationships go to the first layer. Elements that depend only on first-layer elements go to the second layer. And so on. This creates the natural top-to-bottom (or left-to-right) hierarchy that makes architecture diagrams readable.

Crossing Minimization

Within each layer, ELK reorders nodes to minimize the number of edges that cross each other. It uses a technique called layer sweep — repeatedly passing through the layers and swapping node positions until the crossing count stabilizes. Fewer crossings means cleaner, more readable diagrams.

Node Placement

Once the layers and ordering are determined, ELK computes the actual x/y coordinates. Archyl uses the Brandes-Koepf algorithm with balanced alignment, which produces compact layouts where connected nodes align vertically (or horizontally in left-to-right mode) whenever possible. This creates those satisfying straight arrows between related elements.

Edge Routing

ELK routes edges using spline paths, and Archyl recomputes the optimal connection handle — top, bottom, left, or right — for each relationship based on the final node positions. If a system sits above a container, the relationship connects from the bottom of the system to the top of the container. If they're side by side, the connection goes left-to-right.

Compound Graph Support

Architecture diagrams aren't flat. Containers live inside systems. Components live inside containers. Overlays group related elements. Auto Layout handles all of these nesting relationships.

When a system contains containers on the diagram (displayed as a compound group node), ELK treats it as a compound parent with internal children. The children are laid out within the parent, and the parent resizes to fit. The internal layout uses the same algorithm as the top level — layered, with crossing minimization and alignment — so the structure inside a system group is just as clean as the structure outside it.

Overlays work the same way. If an overlay has configured elements, those elements are treated as children of the overlay during layout. The overlay resizes and repositions to encompass its members with proper padding. Even "floating" overlays — those without explicit element assignments — are handled: Auto Layout detects which nodes are visually inside the overlay's bounds and keeps them together.

Post-Processing: Alignment and Grid Snapping

The raw ELK output is good but not perfect. Archyl applies two post-processing passes to refine it.

Chain alignment finds connected nodes that are nearly aligned on the perpendicular axis and forces them to the exact same center line. This uses a Union-Find structure to group chains of connected nodes, then computes the median center and aligns the entire chain. The result is perfectly straight arrows between connected elements — no more "almost vertical" lines that look sloppy.

Overlap resolution detects nodes that ended up too close after alignment and pushes them apart. It runs iteratively up to five passes, which handles cascading shifts where moving one node creates a new overlap with another.

After both passes, every position snaps to a 20-pixel grid that matches the React Flow background. This means elements align precisely with the grid lines, creating a polished, intentional look.

Direction Toggle

Auto Layout supports two directions: Top-to-Bottom and Left-to-Right. A toggle next to the Auto Layout button lets you switch between them.

Top-to-Bottom is the default and works well for most architecture diagrams — external actors at the top, systems in the middle, infrastructure at the bottom. Left-to-Right works better for pipeline-style architectures or flow-oriented views where data moves horizontally through processing stages.

The direction affects everything: layer assignment, crossing minimization, alignment chains, and handle computation. Switch directions and the entire diagram reorients.

What Gets Persisted

Auto Layout isn't just a visual trick. After the animation completes, every computed position is persisted to the server. Node positions, overlay bounds, compound group dimensions, and edge handles are all saved. Close the browser, come back tomorrow, and the layout is exactly as Auto Layout left it.

Edge handle updates are batched into a single API call for efficiency. Overlay resizes are persisted individually. Node positions are sent in bulk. Nothing is lost.

Global Architecture View

Auto Layout works on the Global Architecture page too — not just within individual projects. When you're looking at systems across your entire organization with dozens of cross-project relationships, manual layout is especially painful. Auto Layout brings the same one-click organization to the global view, with the same compound graph support for system groups containing their containers.

When to Use It

Auto Layout is most useful in three scenarios:

After AI discovery. When Archyl's AI analyzes a repository and generates a C4 model, the initial positions are computed algorithmically but may not reflect the layout you'd choose. Auto Layout gives you a clean starting point.

After significant changes. You've added five new containers, reorganized relationships, and moved components between systems. The diagram has gotten messy. Auto Layout recomputes everything from scratch.

When exploring a new project. You've joined a project and want to understand its architecture. The diagram was laid out for someone else's mental model. Auto Layout produces a standard, readable arrangement that makes the structure clear.

You can always adjust individual elements after running Auto Layout. It's a starting point, not a constraint.

Getting Started

Auto Layout is available now on all plans and on every diagram — project-level and global. Open any diagram, click the Auto Layout button in the toolbar, and watch your architecture organize itself.

Your architecture deserves to be readable. Auto Layout makes sure the diagram doesn't get in the way.

For more on building effective architecture diagrams, see Introduction to the C4 Model. To understand how Auto Layout interacts with cross-project views, explore Real-Time Collaboration and Global Architecture. For analyzing the relationships that Auto Layout arranges, try Impact Radar.