> For the complete documentation index, see [llms.txt](https://docs.tdlformat.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tdlformat.dev/readme.md).

# README

TDL is a modern, text-based language for defining software architecture diagrams. It is optimized for:

1. **LLM Generation**: Flat, bracket-free structure that models generate and edit reliably (see [Benchmarks](/appendix/benchmarks.md) for how that trades against token count)
2. **Human Readability**: Clean, indentation-based syntax inspired by Python and YAML
3. **Professional Output**: Renders into beautiful, presentation-ready diagrams

## Example

```tdl
@arch Microservices Architecture

[nodes]
  gateway:API Gateway|icon:aws-api-gateway
  auth:Auth Service|icon:gilbarbara-auth0
  db:User Database|cyl|icon:devicon-postgresql

[edges]
  gateway->auth:validates
  auth->db:queries

[groups]
  backend:Backend Services
    auth
    db
```

![Rendered diagram](https://1360511108-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPILxDEkE0iV8e8pSQ5RS%2Fuploads%2Fgit-blob-e7121a23b5f9834d919d109dcd5bed72ced2d324%2Ftdl-README-1.svg?alt=media)

## Documentation

* [**Specification**](/appendix/specification.md): The formal TDL language standard
* [**Getting Started**](/getting-started/first-diagram.md): Write your first TDL diagram
* [**Syntax Reference**](/reference/syntax.md): Complete syntax guide

## Implementations

* [**Architoon**](https://architoon.xyz) - Web editor, plus:
  * `@architoon/tdl-mcp` - MCP server for Claude Code and other MCP-compatible AI assistants
  * VS Code extension with live preview and export (Marketplace listing coming soon; build locally today)