Quick Start

Build your first diagram in six steps

Quick Start

Build your first validated architecture diagram in six steps. Each step introduces one new Datro concept. By the end you will have a complete, styled, constraint-checked diagram ready to export as SVG.

Open Diagram Maker

Follow along in the live editor — paste each snippet and click Validate.

Step 1 — Write your first nodes and edges

Every .dtro file starts with a magic header. After it, declare nodes (entities) and edges (relationships). Paste this into the editor:

arch.dtro

#!DATRO 1.0

node frontend { type: web      label: "React App" }
node backend  { type: service  label: "NestJS API" }
node db       { type: database label: "PostgreSQL" }

edge frontend -> backend { kind: http }
edge backend  -> db      { kind: query }

ℹ️

Magic header required

The `#!DATRO 1.0` line on line 1 is mandatory. The parser returns `E100` if it is missing.

Step 2 — Add `attrs` for richer metadata

The attrs block holds arbitrary key-value metadata. Values can be strings, numbers, booleans, or arrays. Common attributes are tech, owner, deprecated, and sla.

DATRO

node backend {
  type:  service
  label: "NestJS API"
  attrs {
    tech:  "nestjs"
    owner: "platform-team"
  }
}

Attributes pass through to the JSON IR and appear as tooltips in the rendered SVG — useful for on-call and SLA metadata.

Step 3 — Add edge metadata

Edges have a kind (semantic relationship type), an optional label, a weight (relative traffic), and an async flag. Async edges render as dashed lines.

DATRO

edge backend -> stripe {
  kind:  http
  label: "charge API"
  async: false
}

Field	Type	Required	Default	Description
`kind`	EdgeKind "http""grpc""query""publish""subscribe""read""write""deploys""monitors""depends""…21 total"	Yes	`unknown`	Semantic relationship type
`label`	string	No	—	Short text displayed on the edge line
`weight`	number	No	`1.0`	Relative traffic weight — heavier edges render thicker
`async`	boolean	No	`false`	When true, edge renders as dashed (fire-and-forget pattern)

Step 4 — Group nodes into clusters

Use a group block to cluster related nodes. Groups render as labelled subgraph boxes in the SVG. A node can belong to only one group.

DATRO

group data_tier {
  label:   "Data Layer"
  members: [db, redis_cache]
}

node redis_cache { type: cache label: "Redis" }

edge backend -> redis_cache { kind: read  label: "session" }

💡

Groups vs. node.group

You can also assign a group directly on the node with `group: data_tier`. Both styles are valid; the `group` block's `members` list takes precedence.

Step 5 — Add an architectural constraint

Constraints are machine-checked architectural rules. The validator evaluates them against the IR and returns E501 errors when a rule is violated.

DATRO

constraint {
  id:       "no-db-external"
  rule:     "database !-> external"
  message:  "Databases must not connect to external services"
  severity: error
}

The rule database !-> external means: no node of type database may have a directed edge to any node of type external. This blocks accidental direct DB → third-party API calls.

Step 6 — Add layout hints and a theme

Control how the diagram is arranged with a layout block and define a colour palette with a theme block. The accessibility check fires W602 if any colour falls below WCAG AA contrast.

DATRO

layout { direction: LR  algo: dagre  node_sep: 60  rank_sep: 120 }

theme {
  palette {
    service:    "#D0E8FF"
    database:   "#FFE8C0"
    web:        "#E8D0FF"
    cache:      "#C0FFE8"
    background: "#FFFFFF"
  }
  accessibility { min_contrast: AA }
}

💡

WCAG contrast is automatic

The DOT exporter automatically picks black or white font colour for each node fill using the WCAG 2.1 relative luminance formula — zero configuration needed.

Next steps

Read the Language Reference for the full syntax of every block type.
Use the CLI Reference to validate, format, and export from the command line.
Learn how to embed diagrams in Markdown docs with the remark or markdown-it plugin.

Open Diagram Maker

Your diagram is ready to render — click Render → SVG in the editor toolbar.