DSL Editor

Ln 1, Col 1

Nodes —

Edges —

Flows —

Lines 0

UTF-8 · DSL

Output

Preview

— fps

0Nodes

0Edges

0Flows

Legend

Node

Connection

Flow particle

ArchFlow DSL · v0.1.0

Language Reference

ArchFlow DSL is a declarative language for describing system architecture and animated data flow. Write plain-text diagrams that compile in real time to interactive visualizations.

Contents

01Node Declaration 02Connections 03Flow Animations 04Groups & States 05Layout Engine 06Color Reference 07Export Formats 08Full Grammar (EBNF)

01 Node Declaration

Nodes are the fundamental building blocks of a diagram. Each node represents a service, component, or system entity. Declare a node with the node keyword followed by a unique identifier.

DSL

node api # Auto-positioned node node database at (400, 300) # Explicit position (x, y) node cache at (400, 150)

Parameter	Type	Required	Description
identifier	string	Required	Unique name for the node. Used in connect and flow declarations.
at (x, y)	number pair	Optional	Explicit canvas position in a 800×600 coordinate space. Scaled to viewport automatically.

💡If no position is given, the layout engine places nodes automatically using a directed acyclic graph (DAG) algorithm based on your connect and flow declarations.

02 Connections

Connections define structural relationships between nodes. They render as static dashed lines with arrowheads and represent the topology of your system — not data movement (use flows for that).

DSL

connect frontend -> api connect api -> database connect api -> cache

ℹ️Both connect and flow declarations influence the automatic layout engine — connected nodes are pulled into proximity across the same DAG level.

03 Flow Animations

Flows define animated data movement between nodes. Each flow renders as a moving particle along a bezier path. Multiple options can be chained in any order after the node pair.

DSL

flow api -> database # Default: speed 1, blue, loop flow api -> cache speed 2.0 color green # Fast green flow flow worker -> queue speed 0.5 color amber loop # Slow amber, looping

Option	Values	Default	Description
speed	0.1 – 5.0	1.0	Particle velocity. Values above 2.0 spawn multiple particles to maintain visual density.
color	named color	blue	Particle color. See Color Reference (§06) for all supported names.
loop	flag	true	Particles restart from the source node after reaching the target.

04 Groups & States

Groups logically cluster related nodes. States define alternative animation configurations — for example, an idle state vs. a high-load state. Both accept nested statements.

DSL

group backend { node api node worker node database } state high_load { flow client -> api speed 4.0 color red }

⚠️Group and state declarations are parsed but visual grouping boundaries are planned for a future release. Nested node declarations are fully supported today.

05 Layout Engine

The layout engine runs automatically when coordinates are omitted. It uses a topological sort to determine node levels, then distributes nodes evenly across the canvas.

Mode	Trigger	Behavior
Explicit	`at (x, y)` provided	Coordinates scaled from 800×600 space to current viewport size.
DAG Auto	No coordinates	Topological sort assigns column depth; nodes distributed vertically within each column.
Mixed	Some nodes positioned	Positioned nodes are fixed; unpositioned nodes use DAG layout in remaining space.

06 Color Reference

Use these named colors in flow … color <name> declarations.

Name	Hex	Preview

07 Export Formats

Format	Animated	Best for	Player required
Lottie JSON	✓	Web, iOS, Android embeds	Yes — lottie-web, react-lottie
SVG	✗	Figma, Illustrator, Markdown	No
Animated GIF	✓	GitHub README, Notion, Slack	No

💡Click Export in the top bar after compiling to open the export dialog. The Export button is disabled until a valid diagram has been compiled.

08 Full Grammar (EBNF)

EBNF

program ::= statement* statement ::= node_decl | connect_decl | flow_decl | group_decl | state_decl node_decl ::= "node" IDENT ("at" position)? position ::= "(" NUMBER "," NUMBER ")" connect_decl ::= "connect" IDENT "->" IDENT flow_decl ::= "flow" IDENT "->" IDENT flow_opt* flow_opt ::= "speed" NUMBER | "color" IDENT | "loop" group_decl ::= "group" IDENT "{" statement* "}" state_decl ::= "state" IDENT "{" statement* "}" IDENT ::= [a-zA-Z_][a-zA-Z0-9_]* NUMBER ::= [0-9]+ ("." [0-9]+)?

Examples Library

Ready-to-use Diagrams

Click any example to load it into the editor. Each one demonstrates a different architectural pattern — from simple pipelines to complex microservice meshes.

Beginner

Intermediate

Advanced