tld

tld is an opinionated, flexible diagramming tool with rich featureset to help you visualize, understand, and maintain your software architecture. Inspired by C4 model, designed with multiple opt-in features to answer evolving needs of software teams.

Highlights

• UI: A frontend optimized to handle complex architectures, with intuitive design and polished with tools to manage contextual views.

• Standalone Distribution: A single, dependency-free binary containing both the server and the web application. Available as CLI + WebUI or Native app(windows and macOS).

• CLI that speaks agent: Use the agent skill and use your agent to create a diagram of your codebase with the exact detail level you need. Prompt the agent to add/remove details you see fit. Here are some examples that were generated using the agent skill.

  • Kubernetes

  • pytorch

  • kafka

  • .NET eShop reference

• Editor and Github Integration: Jump to the code in your editor or Github from diagrams, or open the code symbol in diagram from your editor to visualize the code using the VSCode extension.

• Mermaid Integration: Paste your mermaid diagrams into canvas to import them or export as mermaid for quick sharing.

• Markdown Notes Support: Add notes and documentation for your diagram or link an existing one, preview and edit diagrams and markdown side-by-side.

• Mermaid Integration: Easily sync your diagrams with mermaid blocks in a markdown file for portable viewing in any markdown viewer. Link to docs

• Bi-directional Sync: (Experimental) Seamlessly sync changes between your local YAML files, the self-hosted web UI, and the cloud version at tlDiagram.com.

• Git diff visualization: (Experimental) Sync and visualize the changes you or your agent are making live in diagram form. Inspect the dependencies and intervene when necessary.

• Diagrams as Code: (Experimental) Manage architectural evolution alongside your source code with synchronous add/connect/update/remove commands that apply immediately and keep local YAML in sync.

• Automated Codebase Analysis: (Experimental) Built-in tree-sitter integration to automatically discover architecture components in Go, Java, Python, C++, and TypeScript (more soon™ (hopefully)).

Quick Start

Docker

Both Compose files use ghcr.io/mertcikla/tld:latest from GitHub Container Registry. Start either stack (Docker Compose v2):

# SQLite
docker compose up

# Or PostgreSQL with pgvector, required by the core migrations
docker compose -f docker-compose.postgres.yml up

Native binary

macOS and Linux

curl -LsSf https://tldiagram.com/install.sh | sh -s serve --open

Windows

powershell -ExecutionPolicy ByPass -c "irm https://tldiagram.com/install.ps1 | iex; tld serve --open"

Documentation

Visit docs for more info.

Deployment & Self-Hosting

tld has native-desktop builds for macOS and windows. Look for tld-desktop binaries in releases.

tld designed to be run fully offline, behind a reverse-proxy or in your infrastructure or as a local development tool.

Run tld serve to start a local SQLite-backed instance, or configure PostgreSQL in ~/.config/tldiagram/tld.global.yaml or via env vars

export TLD_DB_DRIVER=postgres
export TLD_DATABASE_URL='postgres://user:pass@postgres:5432/tld?sslmode=require'
export TLD_PUBLIC_URL='https://example.com'
export TLD_HOST=127.0.0.1
export PORT=8060

tld serve

The PostgreSQL database must have pgvector support.

Mobile

There are Mobile apps available in both App Store and Play Store they are mostly cloud-oriented and free but require tldiagram.com account. They are good for quickly checking stuff on-the-go, small screens are hard for full featured diagram authoring but they still received some development effort and attention to make authoring possible on mobile.

Commands Reference

tld --help

or

Use tld [command] --help for more information about a command