Shapes

Shapes provide visual differentiation for different component types.

Syntax

id:Label|shape

Available Shapes

TDL supports 12 shapes:

rect (default)

Standard rectangle. Used for services, APIs, generic components.

api:API Gateway|rect
api:API Gateway        # rect is default

cyl (cylinder)

Database/storage shape. Used for databases, caches, data stores.

db:PostgreSQL|cyl
redis:Redis Cache|cyl
s3:S3 Bucket|cyl

cloud

Cloud shape. Used for external services, cloud providers, user-facing apps.

web:Web App|cloud
users:Users|cloud
external:Third Party API|cloud

diamond

Decision/routing shape. Used for load balancers, routers, decision points.

lb:Load Balancer|diamond
router:API Router|diamond

oval

Rounded shape. Used for processes, actors, soft boundaries.

user:End User|oval
process:Background Job|oval

hex (hexagon)

Hexagonal shape. Used for services in hexagonal architecture, adapters.

adapter:DB Adapter|hex
port:HTTP Port|hex

doc (document)

Document shape. Used for files, configs, documentation.

config:config.yaml|doc
schema:schema.json|doc

grp (group)

Visual grouping. Used to represent logical boundaries.

vpc:VPC|grp
cluster:K8s Cluster|grp

terminator

Rounded rectangle. Used for start/end points in flows.

start:Start|terminator
end:End|terminator

data

Parallelogram. Used for data input/output.

input:User Input|data
output:Report|data

subproc (subprocess)

Rectangle with double sides. Used for subprocess or external process.

batch:Batch Process|subproc
external:External System|subproc

manual

Trapezoid. Used for manual operations.

review:Manual Review|manual
approval:Manager Approval|manual

Shape Selection Guide

Component Type	Recommended Shape
API / Service	rect (default)
Database	cyl
Cache	cyl
Queue	cyl
External Service	cloud
User / Actor	oval or cloud
Load Balancer	diamond
Config File	doc
Logical Group	grp
Start/End	terminator

Examples

Microservices

@arch
[nodes]
  gateway:API Gateway|diamond
  auth:Auth|rect
  users:Users|rect
  orders:Orders|rect
  db:PostgreSQL|cyl
  cache:Redis|cyl
  queue:RabbitMQ|cyl

[edges]
  gateway->auth
  gateway->users
  gateway->orders
  users->db
  orders->db
  auth->cache
  orders-->queue

Rendered diagram

Data Pipeline

@arch
[nodes]
  source:Data Source|cloud
  ingest:Ingestion|data
  process:Processing|subproc
  store:Data Lake|cyl
  output:Reports|doc

[edges]
  source->ingest
  ingest->process
  process->store
  store->output

Rendered diagram

Next Steps

• Connections - Edge types and styling

• Icons - Add cloud provider icons