Your First Diagram

Let's create an architecture diagram step by step.

Goal

We'll build a simple e-commerce backend:

Step 1: Start with the Type

Every TDL document starts with a diagram type declaration:

@arch

Step 2: Add Nodes

Nodes are the boxes in your diagram. Add a [nodes] section:

@arch
[nodes]
  web:Web App
  api:API Server
  db:Database

Rendered diagram

• web, api, db are IDs (used to create connections)

• Web App, API Server, Database are display labels

Step 3: Add Shapes

Different components deserve different shapes. Add shape modifiers with |:

@arch
[nodes]
  web:Web App|cloud
  api:API Server|rect
  db:Database|cyl

Rendered diagram

• |cloud - Cloud shape for frontend/external

• |rect - Rectangle (default)

• |cyl - Cylinder for databases

Step 4: Connect Them

Add an [edges] section to show relationships:

@arch
[nodes]
  web:Web App|cloud
  api:API Server
  db:Database|cyl

[edges]
  web->api:requests
  api->db:queries
  db-->api:results

Rendered diagram

• -> - Solid arrow (synchronous call)

• --> - Dashed arrow (async/response)

• :label - Optional edge label

Step 5: Group Related Components

Use groups to organize:

@arch
[nodes]
  web:Web App|cloud

  [Backend]
    api:API Server
    db:Database|cyl

[edges]
  web->api:requests
  api->db:queries
  db-->api:results

Rendered diagram

Complete Example

@arch
[nodes]
  web:Web App|cloud

  [Backend]
    api:API Server
    cache:Redis|cyl
    db:PostgreSQL|cyl

[edges]
  web->api:HTTP
  api->cache:get/set
  api->db:queries
  cache-->api:cached data
  db-->api:results

Rendered diagram

What's Next?

• Shapes - All 12 available shapes

• Connections - Edge types in detail

• Icons - Add cloud provider icons