Skip to content
tlDiagram

Core Concepts

Core Concepts

Section titled “Core Concepts”

tldiagram is built upon a strict, powerful mental model that allows for scalable, interactive architectural diagramming. Understanding these core concepts is essential to getting the most out of the platform.

The Diagram Hierarchy

Section titled “The Diagram Hierarchy”

Unlike flat diagramming tools, tldiagram uses a strict hierarchical structure, inspired by the C4 model.

Parent-Child Relationships

Section titled “Parent-Child Relationships”

Every diagram in tldiagram exists within a hierarchy. A diagram can contain other diagrams as “children,” allowing you to drill down from high-level system contexts to granular component details. This strict nesting helps maintain a clean, navigable architecture.

Hierarchy Operations

Section titled “Hierarchy Operations”

The platform supports powerful structural operations:

  • Atomic Reparenting: You can move a diagram—along with its entire subtree of child diagrams—to a new parent in a single atomic operation.
  • Subtree Deltas: Changes made to a shared component or a child diagram can propagate or be versioned intelligently across the system.

Structural Constraints

Section titled “Structural Constraints”

To ensure your architecture remains navigable and logical, the system enforces certain architectural invariants. For example, cyclical nesting (where a diagram is a child of itself, directly or indirectly) is strictly prohibited. The system also manages depth limits to keep performance optimal.

Linking Mechanisms

Section titled “Linking Mechanisms”

To support complex architectures without breaking the strict hierarchy, tldiagram provides two distinct types of links:

Section titled “Child Links (Structural)”

Child links define the hard hierarchy of your diagrams. When a node in Diagram A links to Diagram B as a child, Diagram B becomes a structural descendant of Diagram A. This dictates how diagrams are nested and navigated when drilling down.

Section titled “Portal Links (Object-Level)”

Portal links are “soft” links that connect objects across different diagrams without altering the strict hierarchy. These are essential for representing cross-cutting concerns, shared databases, or external services that might be referenced in multiple contexts but only structurally belong to one parent.