Flowchart

About flowcharts

A flowchart maps the steps of a process — decisions, operations, inputs, outputs, and the paths between them — using a standardized set of symbols connected by arrows. Engineers use them to specify algorithms; business analysts use them to document workflows; quality teams use them to trace failure modes. They are among the most universally understood technical diagrams across every industry.

Schematex follows the ISO 5807:1985 symbol conventions for flowchart shapes and uses a Mermaid-compatible DSL so existing Mermaid flowcharts transfer directly. This page documents what the parser accepts today.

1. Your first flowchart

The smallest useful flowchart: a decision with two outcomes.

Four rules cover 80% of usage:

1. Start with flowchart followed by a direction: TD, LR, BT, or RL.
2. Each node is ID[Label] — the shape brackets determine the node type (see §2).
3. Connect nodes with -->. Add a label between pipe characters: -->|Yes|.
4. Nodes are created automatically when first referenced in an edge — but explicit declarations let you set shapes and labels independently.

Comments start with %% on their own line.

2. Node shapes

Each node shape is written as ID<brackets>Label<brackets>. The ID must start with a letter and may contain letters, digits, _, and -.

3. Edges

An edge connects two nodes. The connector symbol determines the visual style and whether a label or arrowhead is present.

3.1 Edge types

3.2 Edge labels

Two syntaxes attach a label to an edge:

Pipe label — placed between | characters directly after the arrow:

A -->|Yes| B
A -.->|optional| B
A ==>|critical| B

Inline label — text placed between the dashes, before the arrow character:

A -- success --> B
A -- error --x C

Both produce identical results. Pipe label is more common when sharing a diagram with Mermaid tools.

3.3 Chains

Connect three or more nodes in a single line:

A --> B --> C --> D

This is equivalent to three separate edge statements.

3.4 Fan-out with &

Use & to include multiple nodes on either side of an arrow. The parser generates the full cross-product of edges:

A & B --> C        %% A→C and B→C
A --> B & C        %% A→B and A→C
A & B --> C & D    %% four edges: A→C, A→D, B→C, B→D

4. Subgraphs

A subgraph groups related nodes into a labeled cluster with a visible border.

subgraph "Title"
  A --> B
end

Three subgraph header forms are accepted:

Subgraphs can have their own direction override:

subgraph sg1 "Frontend"
  direction LR
  ui[React App] --> api[API Client]
end

5. Styling

5.1 Semantic classes

Assign CSS class names to nodes for theme-level visual grouping. Classes are defined with classDef and applied with class.

classDef danger fill:#f9c,stroke:#c00
classDef safe fill:#cfc,stroke:#090
class errorNode danger
class successNode safe

5.2 Per-node style overrides

style nodeId fill:#f9f,stroke:#333,stroke-width:4px

Accepts standard CSS property names. Multiple properties are comma-separated.

6. Labels & comments

• Direction: flowchart TD — first token after flowchart or graph. TD and TB are equivalent.
• Title: flowchart LR "My diagram" — optional quoted string after the direction.
• Edge labels: pipe syntax -->|label| or inline -- label -->.
• Comments: %% at the start of a line (after leading whitespace).

flowchart LR
%% This is a comment — ignored by the parser
A[Step 1] --> B[Step 2]  %% inline %% is NOT supported — only line-start %%

7. Reserved words & escaping

Reserved at line start: flowchart, graph (header), subgraph, end, direction, class, classDef, style, linkStyle.

Reserved ID characters: IDs match [A-Za-z0-9_-] starting with a letter. Do not use spaces or operator characters in node IDs.

Operator tokens to avoid inside IDs: -->, ---, -.->, ==>, <-->, --x, --o, |, &.

Labels with special characters: The label is everything inside the shape brackets. Special characters are supported inside labels as-is — brackets/braces that would be ambiguous are closed by the matching closing token.

8. Common mistakes

9. Grammar (EBNF)

document       = header (blank | comment | subgraph-block | direction-stmt
                        | class-stmt | classdef-stmt | style-stmt
                        | linkstyle-stmt | chain-stmt)*

header         = ("flowchart" | "graph") ( WS direction )? ( WS title )? NEWLINE
direction      = "TD" | "TB" | "BT" | "LR" | "RL"
title          = '"' any-char-but-quote* '"' | bare-word

subgraph-block = "subgraph" ( WS subgraph-header )? NEWLINE
                   ( WS? "direction" WS direction NEWLINE )?
                   statement*
                 "end" NEWLINE
subgraph-header = id WS "[" label "]"
                | id WS quoted-string
                | quoted-string
                | id

chain-stmt     = node-group ( WS edge-op WS pipe-label? WS node-group )* NEWLINE
node-group     = node-ref ( WS "&" WS node-ref )*
node-ref       = id shape-suffix?
shape-suffix   = "[" label "]"          %% rect
               | "(" label ")"          %% round
               | "([" label "])"        %% stadium
               | "{" label "}"          %% diamond
               | "{{" label "}}"        %% hexagon
               | "[[" label "]]"        %% subroutine
               | "[(" label ")]"        %% cylinder
               | "((" label "))"        %% circle
               | "(((" label ")))"      %% double-circle
               | "[/" label "/]"        %% parallelogram
               | "[\" label "\]"        %% parallelogram-alt
               | "[/" label "\]"        %% trapezoid
               | "[\" label "/]"        %% trapezoid-alt
               | ">" label "]"          %% asymmetric

edge-op        = "-->" | "---" | "-."-".->" | "==>" | "<-->" | "--x" | "--o"
               | inline-label variants of the above
pipe-label     = "|" text "|"

class-stmt     = "class" WS id-list WS class-name NEWLINE
classdef-stmt  = "classDef" WS class-name WS css-props NEWLINE
style-stmt     = "style" WS id WS css-props NEWLINE
linkstyle-stmt = "linkStyle" WS ...    %% parsed but not yet rendered

comment        = "%%" any NEWLINE
id             = [A-Za-z] [A-Za-z0-9_-]*

Authoritative source: src/diagrams/flowchart/parser.ts. If this diverges from the parser, the parser wins — please open an issue.

10. Standard compliance

Schematex flowcharts follow ISO 5807:1985 symbol conventions. The DSL syntax is intentionally compatible with Mermaid flowchart so diagrams created in one tool can be used in the other.

What is implemented today:

• ✅ All five directions: TD, TB, BT, LR, RL
• ✅ 13 node shapes (rect through asymmetric)
• ✅ 7 edge kinds: solid, no-arrow, dotted, thick, bidirectional, crossed, round-end
• ✅ Pipe labels (-->|text|) and inline labels (-- text -->)
• ✅ Edge chains (A --> B --> C)
• ✅ Fan-out with & (cross-product edges)
• ✅ Subgraphs with optional id, label, and per-subgraph direction
• ✅ classDef / class semantic grouping
• ✅ Per-node style CSS overrides
• ⏳ linkStyle rendering — parsed but visual application pending
• ⏳ Shape rendering for all 13 shapes — M1 fully renders rect/round/stadium/diamond/parallelogram; remaining shapes fall back to rect
• ⏳ Swim-lane layout variant

References:

• ISO 5807:1985 — Information processing — Documentation symbols and conventions for data, program and system flowcharts, program network charts and system resources charts
• Mermaid flowchart documentation — https://mermaid.js.org/syntax/flowchart.html

11. Roadmap

Planned — not yet parseable. Do not use these in generated DSL today; the parser will reject or ignore them.

• linkStyle visual rendering — linkStyle 0 stroke:#f00 is parsed and stored but not yet applied by the renderer.
• Full shape rendering for all 13 shapes — subroutine, cylinder, circle, double-circle, hexagon, asymmetric, trapezoid, and parallelogram-alt fall back to rect in M1.
• Swim-lane layout — horizontal bands grouping nodes by actor or system (Mermaid subgraph with direction TB inside LR root).
• %%{init: {…}}%% init block — Mermaid-compatible theme and layout initialization block.

Track in the GitHub issues if you need any of these sooner.