Create Diagram

Create Diagram

Build a tld workspace that helps someone understand a system by moving from broad architecture to useful detail.

When to Use

• The user asks for a diagram, architecture map, component map, dependency map, or data-flow view.
• The target is a local codebase, service, package, multi-service app, or described system.
• The useful output is a navigable tld model rather than prose alone.

When NOT to Use

• The user only wants code explanation and did not ask for a visual model.
• The task is to change application behavior.
• The diagram is unrelated to software/system structure and does not benefit from tld's hierarchy.

tld Mental Model

tld models architecture as a hierarchy of elements and connectors.

• An element is the node in the knowledge graph. It can represent a system, subsystem, service, module, class, database, external system, user, or any other entity relevant to the architecture.
• A view is the canvas inside an element. Add children with --parent <ref> to create drill-downs. There is no separate "create view" command. View is used to group related elements, or to explain a subsystem in more detail.
• A connector is the edges of the graph, describes a relationship between elements. The view is inferred from the elements' shared parent.
• A kind is a broad role such as system, container, component, database, person, or external; omit it if it doesn't fit any clear category. --kind takes a single shell token, so quote multi-word kinds (e.g. --kind "external system").
• A technology is metadata. Prefer catalog names suggested by tld tech suggest.

The goal is not to mirror folders. Build a navigable map of how control, data, ownership, and dependencies move through the system.

CLI Basics

Use the flat CLI shape:

tld add "<name>" --ref <ref> --kind <kind> --parent <parent-ref>
tld connect --from <source-ref> --to <target-ref> --label "<specific interaction>"
tld validate

For root-level elements, omit --parent.

If a technology label is uncertain, check it first:

tld tech suggest "<technology name>"

If the same real element appears in another view, reuse the same --ref with a different --parent. This creates another placement, not a duplicate element, and highly desired to truly show interaction. Add connectors with different labels in each view to show different relationships using --view <optional-view-ref>.

Workflow

Before exploring, check for .tld folder. If it exists we are working in an active workspace and should inspect the existing model and ask the user how they want to update it. If not, run tld init in the codebase root then ask the user the following to set expectations and guide the level of detail:

1. How detailed should the diagram be? (overview, medium, detailed) Use their answers to calibrate the rest of the work. If they don't know, suggest options based on the codebase size once you've done a quick directory scan.

Overview ~5–10 views, 1–2 levels deep Services and their direct dependencies. Entry points, major layers, external systems. Nothing low level.

Medium ~10–30 views, 2–3 levels deep Modules and packages decomposed. Key classes identified and placed. Major data and logic flows wired. Inheritance shown where architecturally significant.

Detailed ~50–200+ views, 4–6 levels deep. Every significant class and function has its own linked view. A reader should be able to navigate from the root view down to understanding a specific method's behavior without opening a file. Connected end-to-end from producers to consumers.