v1.0

1. Introduction

TDL is a text-based language for defining software architecture diagrams. It is designed to be:

1. Token-Efficient: Optimized for LLM generation with minimal characters and tokens.

2. Readable: Uses Python-style indentation and minimal punctuation.

3. Structured: Separates concerns into nodes, edges, groups, and flows.

4. Portable: Core syntax renders meaningfully across all implementations.

5. Extensible: Optional extensions add capabilities without breaking core compatibility.

2. Document Structure

A TDL document consists of a Diagram Type declaration followed by one or more Sections.

@diagram_type [Title]

[section_name]
  content...

2.1. Diagram Types

The document must start with a diagram type declaration starting with @.

Type	Description
@arch	Architecture diagram (default and most mature)
@seq	Sequence diagram
@flow	Flowchart
@state	State diagram
@er	Entity-Relationship diagram

Example:

@arch AWS Cloud Architecture

2.2. Sections

Sections are denoted by square brackets [...]. Content within a section is indented (2 spaces or tab).

Core Sections (all renderers MUST support):

• [nodes]: Define entities.

• [edges]: Define connections.

• [groups]: Define logical groupings.

• [flow]: Define step-by-step processes.

• [tags]: Define reusable styles/properties.

• [nested]: Define hierarchical sub-diagrams.

Extension Sections (renderers MAY support):

• [code]: Define code blocks attached to nodes. (ext:code)

Headers can include metadata:

• [nodes]: Basic header.

• [nodes,5]: Header with expected item count (useful for LLM validation).

• [flow:user_login]: Header with a qualifier/name.

3. Syntax Elements

3.1. Nodes

Nodes are defined in the [nodes] section.

Syntax:

id:Label|property|key:value

• ID: Alphanumeric identifier (no spaces).

• Label: Text displayed on the node.

• Properties: Pipe-separated list of flags or key-value pairs.

Core Properties (all renderers MUST support):

• shape: Shape type (e.g., |cyl, |diamond).

• color: Color name or hex (e.g., |color:red).

• group: Parent group ID (e.g., |group:vpc).

• tags: Comma-separated tags (e.g., |tags:db,secure).

Extension Properties (renderers MAY support):

• icon: Icon identifier (e.g., |icon:aws-s3). (ext:icons)

• code: Code block reference (e.g., |code:block_id). (ext:code)

Supported Shapes:

• rect (default): Rounded rectangle.

• cyl: Cylinder (Database).

• diamond: Diamond (Decision).

• oval: Ellipse (Start/End).

• cloud: Cloud shape.

• hex: Hexagon.

• doc: Document shape.

• grp: Transparent container style.

Example (Core):

[nodes]
  api:API Gateway
  db:Users DB|cyl
  worker:Background Worker|color:blue

Example (with ext:icons):

[nodes]
  api:API Gateway|icon:aws-api-gateway
  db:Users DB|cyl|icon:postgresql

3.2. Edges

Edges are defined in the [edges] section.

Syntax:

source->target:Label|property

Operators:

• ->: Solid arrow (default, unidirectional).

• -->: Dashed arrow (unidirectional).

• ..: Dotted line (no arrowhead).

• <->: Bidirectional solid arrow (arrows on both ends).

• <-->: Bidirectional dashed arrow (arrows on both ends).

Example:

[edges]
  api->worker:jobs
  worker-->db:reads/writes
  api..db:direct access (deprecated)
  client<->server:sync connection
  peer1<-->peer2:gossip protocol

3.3. Groups

Groups connect nodes into visual clusters. Defined in [groups].

Block Syntax:

group_id:Label|property
  member1
  member2

Compact Syntax:

group_id=member1,member2

Properties:

• expandable: Makes the group interactive (collapsible).

• color: Border/fill color.

Example:

[groups]
  vpc:AWS VPC
    subnet_a
    subnet_b

  # Compact
  cluster_1=node_a,node_b

3.4. Flow

The [flow] section describes a sequence of steps, often highlighting specific paths through the architecture.

Syntax:

step_number:source->target:Label

OR

step_number:Title|Description

OR

intro:Title
outro:Title

Example:

[flow:user_signup]
  intro:User Signup Process
  1:client->api:POST /signup
  2:api->db:INSERT User
  3:db-->api:Success

3.5. Nested Diagrams

Nested diagrams allow defining sub-architectures inside a group.

Syntax:

[nested:group_id]
  [nodes]
    inner_node:Label
  [edges]
    inner_node->other_node

3.6. Code Blocks (ext:code)

Extension: This feature requires ext:code. Renderers without this extension MUST parse [code] sections without error but MAY ignore them.

Attach code snippets to nodes using the [code] section.

Syntax:

[code]
  block_id:lang:Title
    code_content...

Link a node to a code block using the |code:block_id property.

4. Lexical Rules

• Indentation: Semantic indentation determines scope (2 spaces or tab).

• Comments: Lines starting with # are ignored.

• Strings: Double quotes " can be used for labels containing special characters (e.g., id:"Label with : colons").

• Identifiers: Alphanumeric, underscores, hyphens.

5. Implementation Notes

5.1. Tokenizer

The lexer emits INDENT and DEDENT tokens based on whitespace analysis, making the parser structure-aware similar to Python.

5.2. Auto-Layout

TDL is designed to be rendered using auto-layout algorithms (e.g., Dagre) rather than absolute positioning.

5.3. Icons (ext:icons)

Extension: This feature requires ext:icons. Renderers without this extension MUST parse |icon:... properties without error but MAY ignore them.

Icons are referenced by ID. Implementations that support ext:icons should provide a library of standard tech icons (AWS, Azure, GCP, generic tech).

6. Extensions

TDL supports optional extensions that add capabilities beyond the core specification. Extensions follow the graceful degradation principle: any valid TDL file MUST parse successfully in any compliant renderer, even if extension features are not displayed.

6.1. Extension Declaration

Extensions can be declared using a pragma comment at the start of the file:

#!ext icons,code
@arch My Architecture
...

6.2. Official Extensions

Extension	Identifier	Features
Icons	icons	|icon:name property, icon libraries
Code Blocks	code	[code] section, |code:block_id property

6.3. Graceful Degradation Rules

Renderers that do not support an extension MUST:

1. Parse without error: Extension syntax is valid TDL

2. Preserve structure: All nodes, edges, groups remain intact

3. Ignore extension properties: Unknown properties are silently skipped

4. Skip extension sections: [code] sections may be ignored

Example: A file with |icon:postgresql renders as follows:

• With ext:icons: Shows PostgreSQL icon

• Without ext:icons: Shows node label only (icon property ignored)

6.4. Extension Versioning

Extensions follow semantic versioning independently of the core spec:

• ext:[email protected] - Icons extension version 1.0

• ext:[email protected] - Code blocks extension version 1.0

The pragma syntax supports versions:

#!ext [email protected],[email protected]