Diagram Linting Rules

When you run tld plan or tld validate, the CLI performs a series of quality checks to help you maintain a clean and professional architectural map. These rules prevent your diagrams from turning into cluttered “walls of boxes” and ensure they serve as a useful “navigatable atlas” for your team.

Validation Levels

You can calibrate the strictness of these checks using the --strictness=[1-3] flag or by configuring your .tld.yaml file:

.tld.yaml

validation:
  level: 2 # Standard (Default)

Level 1: Minimal (Exploration)

Focus: Basic navigation and documentation. Best for initial exploration and rapid prototyping.

Rule	Trigger	Why it matters
Isolated Object	Object has no connections in a diagram	If an object isn’t talking to anything, it either doesn’t belong on this view or a critical connection is missing.
High Density	> 15 objects on one diagram	Human cognitive load peaks at ~12 items. Beyond 15, relationships become impossible to track effectively.
Depth Mismatch	Hierarchy is < 2 levels deep	A flat map of 100 objects is overwhelming. Aim for a hierarchy that allows users to “zoom in” to details.
Low Insight Ratio	Fewer connections than objects	A diagram with many boxes but few lines is “shallow”-it shows an inventory, but not how the system actually works.
Dead-End Drilldown	Object has a link but no sub-diagram	Prevents “broken links” when navigating through the architecture.
Circular Parents	Diagram is its own ancestor	(Hard Error) Prevents infinite loops in navigation and rendering.

Level 2: Standard (Recommended)

Focus: Technical detail and architectural insight. Recommended for day-to-day engineering and onboarding.

Rule	Trigger	Why it matters
Generic Labels	Labels like “calls”, “uses”, or “connects”	These are “low-signal” labels. Use descriptive verbs like “validates JWT”, “publishes event”, or “SQL Query”.
Missing Tech	No technology field (e.g., Go, React)	Knowing the stack is critical for understanding the “how” of a system.
High Density	> 12 objects on one diagram	Keeping diagrams under 12 objects ensures they are readable at a glance without mental strain.

Level 3: Strict (Golden Standard)

Focus: Structural integrity and absolute clarity. Use this for production-grade documentation and system handovers.

Rule	Trigger	Why it matters
Missing Description	description field is empty	A one-sentence summary helps a reader understand a component’s responsibility without having to dive into code.
Generic Naming	Names like “Module 1” or “Stuff”	Vague names make the map harder to search, navigate, and understand.
Missing Label	Connection has no label	An edge without a label tells the reader that a connection exists, but not what it does.
Missing Type	Object has no type	Types (service, db, queue) provide immediate visual context for the role of the component.

Why these rules exist?

The goal of tld is to move beyond static, flat images. By following these guidelines, your diagrams become a living documentation system that is:

1. Navigatable: Easy to drill down from high-level services to low-level implementation details.
2. Searchable: Meaningful names and descriptions make it easier to find components in large systems.
3. Professional: Consistent labeling and metadata (technology, types) ensure the maps are useful for both engineers and stakeholders.

Customizing Rules

You can toggle specific rules off in your .tld.yaml if they don’t fit your current workflow:

.tld.yaml

validation:
  level: 2
  allow_low_insight: true # Disables the "Low Insight Ratio" check