Clean Up and Organize an Imported Architecture

What you'll build

When you import an architecture from a complex README, multi-container codebase, or large GitHub repository, the raw diagram may contain dozens of overlapping nodes and crossing connector lines. In this tutorial, you will systematically clean up, group, and format a raw imported diagram into an executive-ready architectural blueprint.

Before you start

• Have an imported diagram loaded in the canvas (from README, Code, or GitHub import), or open any existing dense diagram.

Step 1: Run Auto Layout to Untangle Crossings

1. If nodes are currently overlapping or spread out randomly, locate the Auto Layout button in the canvas toolbar.
2. Click Auto Layout (Top-to-Bottom).
3. The Dagre layout engine will immediately separate all nodes into distinct horizontal tiers and minimize crossing edges.

Step 2: Establish Logical Boundaries

Now that nodes are spaced out, establish architectural boundaries:

1. Identify components that reside in the same network or deployment zone (e.g. Private Backend Subnet).
2. Press R to select the Rectangle tool and drag a bounding container around those nodes.
3. In the context toolbar, set the stroke to Dashed and reduce fill opacity.
4. Press Cmd/Ctrl + Shift + [ to send the boundary to the back so internal nodes stay interactive.
5. Add a label at the top of the container: Internal Services VPC.

Step 3: Standardize Component Icons and Colors

1. Select each node and review its technology badge.
2. If an imported node has a generic icon, click the Icon Picker and search for its official tech logo (e.g. PostgreSQL, FastAPI, Redis, RabbitMQ).
3. Apply consistent color themes:
   • Blue borders for client and frontend applications.
   • Gray or slate borders for internal microservices.
   • Amber or orange borders for data stores.
   • Purple borders for message buses and streaming topics.

Step 4: Label Critical Connection Edges

1. Review connection lines. If an imported edge has no label, double-click the line.
2. Add protocol and port information (e.g. HTTPS /v1, gRPC :9090, TCP :5432).
3. Ensure arrow heads point in the direction of the client-to-server request initiation.

Review the generated architecture

• Press Shift + 1 to Fit View and review the overall canvas balance.
• Check that the hierarchy flows naturally: Clients at the top, gateways in the middle, services next, and databases at the bottom.
• Confirm that boundary containers clearly separate public ingress from private backend infrastructure.

Customize the diagram

1. Add a Text Node (T) at the top left with a clear title, author, and date.
2. Add an architectural legend if you used custom color codes.
3. If there are pending migration questions, drop a Sticky Note (S) with notes for your team.

Export your result

1. Click Export -> PNG (2x) for high-resolution team sharing.
2. Click Export Markdown to capture the cleaned architecture in text form.

Tips

• Use Shift + Click to select multiple related nodes and move them as a block.
• If you accidentally move a node while editing a boundary, press Cmd/Ctrl + Z to undo immediately.

Limitations

• Auto layout repositions all nodes on the canvas. If you have custom handcrafted coordinate layouts, consider grouping related sections (Cmd/Ctrl + G) before running layout adjustments.