Text to diagram syntax guide: flowcharts, sequence diagrams, C4 maps, and state machines

What the text-to-diagram tool supports

The Text to Diagram Engine turns a small text script into a visual diagram directly in your browser. It is designed for software architecture sketches, cloud system maps, API flows, incident states, and lightweight documentation that can be stored in Markdown or source control.

The supported diagram families are flowcharts, nested subgraphs, sequence diagrams, C4-style container maps, state diagrams, clickable metadata nodes, and themed SVG or PNG exports. The goal is not to replace every feature of a full modeling suite; it is to make common engineering diagrams fast, portable, and private.

Basic flowchart syntax

A flowchart starts with graph TD for top-to-bottom direction or graph LR for left-to-right direction. Each connection uses an arrow such as A --> B. You can define readable labels with square brackets: API[Compute: API Service].

Example: graph TD User[Actor: User] --> Web[Web App] Web --> API[API Service] API --> DB[(Database)] This creates four nodes and three directed edges. Database-style nodes use [(Label)], queue-style nodes use {{Label}}, and decision nodes use {Question?}.

Subgraphs for system architecture

Subgraphs group related components inside a named boundary. This is useful for private subnets, Kubernetes namespaces, SaaS modules, data platforms, or external systems.

Example: graph TD subgraph Private[Private Subnet] API[Compute: API] Worker[Compute: Worker] DB[(Database: PostgreSQL)] end User[Actor: Customer] --> API API --> DB API --> Worker Every subgraph must end with an end line. Node IDs are global across the whole diagram, so do not define the same ID in two different subgraphs unless you intend it to be the same node.

Sequence diagram syntax

A sequence diagram starts with sequenceDiagram. Define actors and participants first, then add messages with arrows such as User->>App: Open dashboard or API-->>App: Response.

Example: sequenceDiagram actor User participant App participant Auth participant API User->>App: Open dashboard App->>Auth: Validate token Auth-->>App: Token accepted App->>API: GET /dashboard API-->>App: Dashboard data App-->>User: Render dashboard

Supported control blocks include loop, alt, opt, and par. Each opened block needs one closing end. Inside a par block, use and to split parallel branches. Inside an alt block, use else to split alternatives.

C4-style container maps

For C4-style diagrams, use a normal flowchart and label nodes as Actor, Software System, Container, Database, or Message Bus. The renderer recognizes common infrastructure labels and assigns compact visual hints.

Example: graph TD Customer[Actor: Customer] Web[Container: Web App] API[Container: API Application] Orders[Container: Orders Service] DB[(Database: Operational Store)] Events{{Message Bus}} Customer --> Web Web --> API API --> Orders Orders --> DB Orders --> Events

For large system design diagrams, keep IDs short and unique, then put human-readable names in labels. This makes exported diagrams easier to maintain over time.

State diagrams for workflows

State diagrams start with stateDiagram-v2. Use [*] for start or end markers, then describe transitions with arrows. Optional labels after a colon explain why the transition happens.

Example: stateDiagram-v2 [*] --> Draft Draft --> Validating : run checks Validating --> Approved : all checks passed Validating --> Failed : errors found Failed --> Draft : fix config Approved --> Live Live --> [*]

Metadata, click events, and documentation links

The diagram tool supports local metadata comments and click links. Metadata is useful for owners, tiers, runtime, backup policy, retention, or runbook hints. Clicking a node can open a browser-side metadata popup or an external documentation link.

Example: click API "https://docs.example.com/api" "Open API docs" %% meta API owner=Platform tier=critical runtime=Node.js %% meta DB owner=Data backup=PITR retention=30d

Because the tool is static and browser-only, click events are handled locally. No user diagram text is sent to a server for processing.

Troubleshooting common syntax errors

If a sequence diagram says a block is missing end, look for loop, alt, opt, or par. Each one needs a matching end after its final message. The words else and and split an existing block; they do not start a new block on their own.

If a subgraph does not appear where expected, check for duplicate node IDs. In Mermaid-style syntax, IDs are global. For example, Events inside a SaaS subgraph and Events inside an External subgraph are the same node ID. Rename one to SaaS_Events or External_Events if they are separate components.

If text overflows a box, shorten the ID and keep the longer name in the label. The renderer wraps labels, but compact IDs still make diagrams easier to read and maintain.

Recommended authoring pattern

Start with a template, rename the nodes, and then add edges one layer at a time. For system design, define the user and edge layer first, then public services, private services, data stores, queues, and observability.

Use graph TD or graph LR for architecture, sequenceDiagram for request lifecycles, and stateDiagram-v2 for workflow status. Save the text source, not just the exported image, so the diagram stays editable.