Editor Usage

tldiagram is designed for high-performance interactive diagramming. This guide covers the core editor features and interactions to help you build architecture diagrams efficiently.

Keyboard Shortcuts

The editor provides several shortcuts to speed up your workflow.

W: Navigate to the Parent Diagram (drill-up).
S: Navigate to the First Child Diagram (drill-down).
A / D: Cycle through Sibling Diagrams at the same level.

Creation & Management

C: Add a new object at the Center of the current view.
Backspace / Delete: Remove the selected object or edge.
Escape: Cancel the current interaction mode (e.g., drawing an edge or searching for a node).

Hierarchical Operations

Shift + W: Create a new Parent Diagram from the current context.
Shift + S: Create a new Child Diagram linked to the selected object.
Shift + A / Shift + D: Create a new Sibling Diagram (layer) for the same context.

Objects & Edges

Adding Objects

You can add objects from the Object Library drawer or by pressing C to place a default object at the center of your view. Once placed, you can drag objects to reposition them.

Editing Objects

Click any object on the canvas to open its Properties Panel. Here you can change:

Name: The display label for the object.
Type: Icons and styles based on the C4 model (Service, Database, Person, Queue, etc.).
Tags: Metadata for filtering and organization.
Git Source: Link the object directly to a repository or specific file.

Git Source Linking

You can enrich your architecture diagrams by linking components directly to their implementation in version control. This provides quick access to the code behind the architecture without leaving your workflow.

To use Git Source Linking:

Select any object (e.g., a service or container) on the canvas.
Open its Properties Panel.
Locate the Git Source input field.
Paste the URL to the relevant repository, directory, or file.
Once linked, a Git icon will appear on the object, allowing you to instantly access the associated source code while reviewing the diagram.

Drawing & Editing Edges

To draw an edge: Click and drag from any handle (the circles on the sides of an object) and drop it onto another object.
Proximity Snap: If you drop an edge near an object center, it will automatically snap to the nearest handle.
Edit Edge: Click an edge to open the Edge Panel, where you can add labels, change direction (forward, backward, bidirectional, or none), and set the line style (e.g., Bezier).
Deleting Edges: Select an edge and press Backspace or Delete.

Interactions

Right-Click Areas (Context Menus)

Canvas (Pane): Right-click the empty background to access canvas-level operations.
Edges: Right-click an edge to quickly delete it or change its properties without opening the full panel.
Objects: Right-click (or long-press) an object for quick actions.

Hold to Interact (Long Press)

For touch devices or a more fluid mouse experience, holding down on an object or edge for a brief moment will activate its context menu or secondary actions. This is particularly useful for:

Quick deletion.
Changing edge endpoints.
Deep-linking operations.

Infinite Zoom (ZUI)

The Explore mode features a Zoomable User Interface (ZUI) that allows you to view your entire architecture hierarchy in one seamless view.

Zoom In: Scroll up or double-click an area to drill down into its details.
Zoom Out: Scroll down to see the broader context and parent diagrams.
Fit View: Use the “Fit View” button in the bottom toolbar to reset the zoom and center all visible objects.

VS Code Extension

You can also use tldiagram directly within VS Code using our official extension. This allows you to:

Open .tld files directly in your IDE.
Link your architecture diagrams to your source code with a split-view experience.
Keep your documentation and code in sync without context switching.

Linking & Associating Diagrams

tldiagram follows the C4 model’s hierarchical structure. You can associate diagrams with objects to create “drill-down” views:

Select an object you want to detail further.
Press Shift + S to create a new child diagram linked to that object.

Alternatively, use the “Set Child Diagram” or “Set Parent Diagram” options in the object properties panel to manually associate existing diagrams.
Linked nodes will show a Zoom-In icon on hover, indicating that a more detailed view is available.

While you can use the mouse to click through your architecture, tldiagram is optimized for speed using a keyboard-first WASD Navigation Paradigm. This allows you to quickly traverse the strict hierarchy:

Use W and S to move up and down the hierarchy (Parent / Child diagrams).
Use A and D to move laterally between sibling diagrams that share the same parent context.

DiagramsGrid Layout

When viewing multiple related diagrams (such as siblings or search results), the platform utilizes a custom DiagramsGrid layout.

Dynamic Organization: Diagrams are automatically arranged in a responsive grid that optimizes for screen real estate and logical grouping.
Contextual Awareness: The grid layout maintains the context of your current hierarchical depth, ensuring you don’t lose your place when viewing multiple architectures side-by-side.