https://github.com/mertcikla/tld
Software architecture diagramming tool. Includes a modern easy to use Frontend + Backend + CLI to enable managing diagrams from the shell or in CI.
https://github.com/mertcikla/tld
agent-skill c4model claude-code-plugin diagram diagramming-as-code diagramming-tool drawio excalidraw gemini-cli-extension gliffy icepanel lucidchart mermaid miro reactflow structurizr
Last synced: 1 day ago
JSON representation
Software architecture diagramming tool. Includes a modern easy to use Frontend + Backend + CLI to enable managing diagrams from the shell or in CI.
- Host: GitHub
- URL: https://github.com/mertcikla/tld
- Owner: Mertcikla
- License: apache-2.0
- Created: 2026-04-23T12:55:32.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-24T10:13:03.000Z (8 days ago)
- Last Synced: 2026-05-24T10:21:32.015Z (8 days ago)
- Topics: agent-skill, c4model, claude-code-plugin, diagram, diagramming-as-code, diagramming-tool, drawio, excalidraw, gemini-cli-extension, gliffy, icepanel, lucidchart, mermaid, miro, reactflow, structurizr
- Language: Go
- Homepage: https://tldiagram.com
- Size: 42.6 MB
- Stars: 8
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
`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 while attempting to intelligently show and hide details.
- **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](./skills/create-diagram/SKILL.md) 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](https://tldiagram.com/app/explore/shared/827bc17d-7d9b-411f-9d03-179fab99bcbd)
- [pytorch](https://tldiagram.com/app/explore/shared/abc56a26-3e20-4235-90fa-e045b2b2ac74)
- [kafka](https://tldiagram.com/app/explore/shared/9d415d7f-b91f-47c0-9dc7-756de2860695)
- [.NET eShop reference](https://tldiagram.com/app/explore/shared/ba6cbf2a-e0ff-468a-87e5-f720d35f448d)
- **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](https://marketplace.visualstudio.com/items?itemName=tlDiagram-com.tldiagram).
- **Mermaid Integration**: Copy 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 with rich UI.
- **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) A git/terraform like workflow (`plan`/`apply`) to manage architectural evolution alongside your source code.
- **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
macOS and Linux
```bash
curl -LsSf https://tldiagram.com/install.sh | sh -s serve --open
```
Windows
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://tldiagram.com/install.ps1 | iex; tld serve --open"
```
## Deployment & Self-Hosting
`tld` designed to be run fully offline, behind a reverse-proxy or in your infrastructure or as a local development tool.
```bash
export TLD_DB_DRIVER=postgres
export TLD_DATABASE_URL='postgres://user:pass@postgres:5432/tld?sslmode=require'
export TLD_PUBLIC_URL='https://app.example.com'
export TLD_HOST=127.0.0.1
export PORT=8060
tld serve
```
The PostgreSQL database must have `pgvector` support.
Run `tld serve` without PostgreSQL settings to start a local SQLite-backed instance.
### Configuration
Various configuration options are available in `~/.config/tldiagram/tld.yaml`
# Documentation
Visit [docs](https://tldiagram.com/docs) for more info.
## Commands Reference
`tld --help`
```text
Usage:
tld [command]
CRUD actions on resources:
add Add or update an element in elements.yaml
connect Add a connector between two elements
remove Remove workspace resources
rename Rename an element in elements.yaml
update Update a resource field with a value
Secondary actions:
analyze Extract symbols from source files and upsert them as workspace elements
apply Apply plan to the tldiagram.com
check Check workspace health and diagram freshness
completion Generate the autocompletion script for the specified shell
diff Show differences between local workspace and server
export Export all diagrams from an organization to the local workspace
help Help about any command
init Initialize a new tld workspace
login Authenticate the CLI with a tlDiagram server
plan Show what would be applied
pull Pull the current server state into local YAML files
render Render a workspace view to text output formats
serve Start the local tlDiagram web server
status Show running local tlDiagram processes
stop Stop the local tlDiagram web server
sync Inspect and reconcile workspace sync state
validate Validate the workspace YAML files
version Print the version number of tld
views Show derived view structure for the workspace
Flags:
--compact compact JSON output (no whitespace)
--format string output format: text or json (default "text")
-h, --help help for tld
-v, --version version for tld
-w, --workspace string workspace directory (prefers .tld, then tld; empty when neither exists)
Use "tld [command] --help" for more information about a command
```