Introduction

tlDiagram is a flexible, modern and feature-rich ecosystem for architecture diagramming. Offers many opt-in features to fit into your workflow. You can use it as a simple browser-based diagramming tool, or you can leverage the numerous features to make mapping your codebase and keeping your diagrams up to date easier.

Features at a glance

• Browser-based editor: A modern, intuitive web interface for creating and editing diagrams visually. Designed to manage complexity in rich diagrams.
• Hierarchical views: Create multiple views of the same system. Start with an overview, then drill down into details. Create them when you need it, if you need it. Re-use elements across views for multiple perspectives.
• Code-driven: Use static analysis to generate diagrams from your codebase. See the diff surface in your diagrams, and view dependencies. Keep them in sync as your code changes. Link diagram elements to code symbols and jump straight to the source.
• Deep Markdown support: Write detailed documentation directly in your diagrams. Copy your diagrams as mermaid or paste them right into canvas for quick import.
• GitHub integration: Link your diagrams to GitHub repositories, or code symbols to elements. View code snippets, preview files. Open the source code directly and jump to line from the diagram in your editor.

How the pieces fit together

tlDiagram is an ecosystem with many parts. Pick the workflow that fits.

The browser only

Simple, modern tool for visual diagramming either self-hosted or in the cloud.

AI empowered

Use the agent skill to give your AI agent the ability to read, create, and modify architecture diagrams directly. Ask it to “map this codebase” and watch it build your diagrams. You don’t need the biggest LLM to get value here.

If it misses something, just tell it to explore it further and add more details about the system. It is great to get you 80% of the way there, and then you can fill in the gaps, fine-tune from the browser if you want.

Smart static analysis heuristics

Run tld analyze to get a one-time snapshot of your codebase. It uses Tree-sitter to parse your source files, extract symbols and references with LSP support, and apply heuristics to attempt its best to turn into into a clean architecture diagram. It’s a great way to get a quick overview of an unfamiliar codebase, or to generate a starting point for your diagrams that you can then refine in the browser.

The local web app tld serve

tld serve spins up a local tlDiagram on your machine. Same engine that powers the cloud version, using an embedded SQLite database. No Docker. No external dependencies. Just your browser and the binary.

Everything you build locally can be pushed to the cloud version when you’re ready. Or kept private on your machine forever.

Code-driven with tld watch

This is designed to be the sentinel of your AI based development, driven by treesitter and LSPs instead of the stochastic agent generation to give you a deterministic, real-time link between your code and your diagrams.

Designed like another layer on top of your linting and testing tools. Grants you visual insight into the changes made in a commit to understand its impact on the overall architecture.

This runs the same pipeline first as tld analyze to parse and extract, but then it applies a continuous watching layer on top. Requires a git repository.

The cloud tldiagram.com

The cloud version is where you collaborate. Share diagrams with your team. Work together in real time. It’s the same editor as tld serve, hosted and ready to go.

Your local YAML files push up to the cloud with tld apply. Changes made in the browser pull down with tld pull.

Where to go from here

If you’re new, start with the Quick Start to get the CLI installed and your first diagram published in under five minutes.