Choosing an engine

Every figure in the Studio is written in one engine: the language its source is in, and the renderer that draws it. flowss ships 110 of them. Some are the familiar diagram-as-code languages (Mermaid, PlantUML, Graphviz, D2). Some are chart grammars (Vega-Lite, Plotly). Many are specialist engines built into flowss that compute and check what they draw, such as a fault tree that works out its own probabilities or a state machine that tells you when it is not deterministic. This page is a decision guide. It helps you pick the right engine for the job, compares the engines that are easiest to confuse, explains the practical differences that matter (privacy, offline use, editing, conversion and plans), and ends with an index of every engine in the Studio's library, linked to its reference page.

At a glance

How engines work in the Studio

A figure has exactly one engine at a time. The engine decides the syntax you write in the code sheet, how the canvas draws it, which templates apply, which checks run and which exports and conversions are on offer. You can have several figures open in tabs, each in a different engine.

You do not always have to choose an engine. When you describe a diagram to the AI, paste diagram code or open a file, flowss usually picks the engine for you (see Importing and converting). Choosing one yourself matters when you start from scratch, when you want a particular notation, or when you want an engine's checks or computations.

Picking and changing the engine

Opening the engine library

1. Click Engines & templates at the top of the tool rail. Its tooltip names the current engine. The library opens beside the rail with two tabs, Engines and Templates.
2. Or click the engine name at the top of the code sheet. Its tooltip reads "Engine: Mermaid — change engine", with your engine's name.
3. Or press ⌘K and run Change engine… ("The catalogue of every engine, searchable").

The / key opens the library on the Templates tab with its search box ready. That tab also shows a card describing the current engine, a Recent engines strip of engines you have used lately, and a Recent strip of recent templates.

Finding an engine

The Engines tab lists every engine in collapsible groups, each with a count. Each row shows the engine's colour, its name and how many templates it has. The current engine is highlighted. Hovering over a row shows the engine's description, and for engines drawn by an outside service, a notice saying so (see Where the picture is drawn, below).

The search box reads "Search engines — name, or what you're drawing…". It matches far more than names:

• Names and ids. For example, dbml, pikchr or markmap.
• What you are drawing. For example, critical path, org chart, sequence, project schedule or threat model.
• The tool you are replacing. For example, Visio, dbdiagram, Minitab or Microsoft Project.
• Figures the engine has templates for. For example, forest plot finds Plotly and kaplan meier finds the survival-curve templates.

While you search, every group that contains a match opens to show it. If nothing matches you see No engine matches, with a suggestion to describe what you are drawing instead. Press Escape in the box, or click the × at its end, to clear the search.

What happens when you switch

Clicking an engine row switches the current figure to that engine. It replaces the figure's source with that engine's starter template. It does not convert your diagram. The previous source is kept in the undo history, so ⌘Z brings it back.

To keep your diagram and move it to another engine, convert it instead:

1. Open the ⋮ menu, or press ⌘K, and choose Convert to another engine… ("Instant where a transpiler exists, AI for any other engine").
2. Under Instant, pick a direct translation if one is offered for your engine (see Converting later, below). These run in your browser, cost nothing and need no AI.
3. Otherwise, under Convert with the flowss Studio Agent to…, search for and pick any other engine. AI conversion needs AI on your plan.

Tip: To try another engine without risking your diagram, start a New figure (⌥⌘N) and pick the engine there. Your original stays in its own tab.

Start with what you are trying to show

Find your job in the left column. "Start with" is the best default, and "Also consider" lists the alternatives worth knowing.

Software, systems and architecture

Data models, hardware and protocols

Processes, operations and teams

Planning, product and strategy

Charts and data

Research, science and teaching

Choosing between close cousins

Mermaid, PlantUML, D2 and Graphviz

Choose Mermaid when the diagram has to live in Markdown elsewhere, PlantUML when the audience expects textbook UML, D2 for architecture with grouping, and Graphviz when layout control matters more than style.

Sequence diagrams

Mermaid and PlantUML draw sequence diagrams, and draw what you type. The Sequence & interaction engine also checks the conversation. It flags, for example, a reply returned to someone who never made the call, a call that is never returned, a message to a participant after it has been destroyed, a reply sent on only one branch of an alt, and two branches of an alt whose guards overlap. Use it when the interaction is a specification someone will build from.

State machines, Petri nets and statecharts

Use State machine (FSM) when you need to know the machine is sound: it reports nondeterminism, unreachable states and states with no way out. Use Petri Nets for concurrency, shared resources and synchronisation. Diagram Intelligence reports deadlocks, boundedness and dead transitions there. Use a Mermaid state diagram for a quick illustration.

Schedules: Gantt, PERT and Mermaid Gantt

Risk: fault tree, bowtie, attack tree and RBD

Database schemas: DBML, ERD and Mermaid ER

DBML is the most complete. It has tables, columns, keys, indexes, enums and explicit references, it round-trips with dbdiagram.io, and it gets the most analysis in Diagram Intelligence: missing keys, dangling or unindexed foreign keys and foreign-key cycles. ERD is a minimal entity-relationship language with dependable layout. Use Mermaid ER diagrams when the schema needs to sit in Markdown. DBML converts instantly to both Mermaid ER and ERD.

Charts: Plot, Vega-Lite, Plotly and Vega

Data → Chart writes Vega-Lite for you, and the Figure studio is the place for journal-ready, multi-panel figures from data.

Architecture: Structurizr, D2, Cloud architecture, ArchiMate and SysML

Use Structurizr DSL to define one C4 model and draw several views of it. Use D2 for quick architecture diagrams. Use Cloud architecture for AWS, Azure, Google Cloud and Kubernetes with real containment (account, region, network, zone, subnet, cluster, namespace). It checks things such as a datastore reachable from the internet, or redundancy claimed inside a single zone. Use ArchiMate for enterprise architecture to the 3.2 specification, and SysML v2 for systems engineering with port directions and interfaces checked.

Bit fields: Packet, packetdiag, Bytefield and WaveDrom

Packet & bit fields checks the layout, naming overlapping fields, unclaimed bits and overflows, at 8, 16, 32 or 64 bits a word, in either bit order. packetdiag and Bytefield draw RFC-style layouts in their own syntaxes. WaveDrom is for timing diagrams and also draws register fields.

ASCII to figure: SVGBob, Ditaa and Pikchr

SVGBob turns ASCII art into clean lines. Ditaa does the same with colour-fill markers. Pikchr is a small language of boxes, arrows and splines rather than ASCII art. All three are drawn by an outside render service.

Floor plans

Floor plan (2D) draws a top-down plan. Floor plan (3D) draws the same source as a printable axonometric view. Floor plan (3D WebGL) shows it in an interactive 3D viewer you can orbit, which is best on screen rather than in print.

Mind maps

Markmap (Markdown) draws a mind map from a Markdown outline, and the Studio's Mind map outliner edits it from the keyboard. For a free-form mind map you can rearrange by hand, convert it instantly to a Weave mind map, or work in Weave.

Practical considerations

Where the picture is drawn

Engines fall into three groups by where their pictures are drawn. This matters for confidential work, offline use and automation.

For the outside services, the Studio tells you where you choose. The engine's tooltip in the library, and a line under the code sheet's header, say "Drawn by Kroki, a third-party render service: this source is sent to it." For PlantUML the line reads "Drawn by a PlantUML server (the public plantuml.com unless self-hosted): this source is sent to it."

These services also have daily render limits, counted on each settled edit: 300 renders a day on Free and Starter, 1,000 on Plus, 2,500 on Ultra and 5,000 on Enterprise. Limits reset at midnight UTC. The largest source they accept is 30,000 characters for PlantUML and 100,000 characters for the others.

Warning: If a diagram's source is confidential, choose an engine drawn inside flowss or in your browser. For example, use DBML or Mermaid instead of ERD, D2 or Mermaid C4 instead of Structurizr, and Packet & bit fields instead of packetdiag or Bytefield.

Editing by clicking

Clicking a label on a rendered diagram opens a rename box. The new name is written straight into the source wherever flowss can find the label there. When it cannot, the rename is handed to AI, which needs AI on your plan. The Diagram tools panel adds direct edits: Delete, Duplicate, Add after, Add child, Colour and Bigger. These work fully on Mermaid (except Duplicate in class diagrams), partly on Nomnoml (no Bigger) and Graphviz (Delete and Colour), and other engines use Ask the flowss Studio Agent…. If you like to edit by pointing, Mermaid is the most capable choice. See Data, timeline, TikZ and the diagram tools.

Engines that check and compute

Many engines built into flowss do more than draw. They check the document against the rules of its notation, or compute the numbers it is about, and they write the results into the figure. Examples include State machine, Sequence & interaction, SysML v2, Cloud architecture, DMN, Server Rack, PRISMA 2020, Packet & bit fields, Gantt and every flow-systems engine. Choose one of these when the figure is a claim someone will act on. See Flow-systems analysis in Studio.

Diagram Intelligence coverage

Diagram Intelligence (⇧⌘X) adds structural analysis for Mermaid (flowcharts, state, sequence and class diagrams), Graphviz, D2, PlantUML, Structurizr, Cytoscape, ERD, DBML, Petri Nets, PERT, State machine, Sankey, Causal DAG, Attack tree, Digital logic, Wardley Maps, Newick, Chess and FlowScript. Process diagrams in Mermaid, Graphviz, D2, PlantUML, Structurizr and Cytoscape also get lead time, throughput and the bottleneck.

Converting later

You are never locked in. Convert to another engine… offers:

Any other pair converts with AI. An instant conversion that would lose structure is not applied. Instead you see what would be lost and a Convert with the flowss Studio Agent instead button. Styling that does not carry over is named in a warning after the conversion.

Plans

Every engine in the Studio's library, including FlowScript, works on every plan, including Free, with no limit on how much you draw. Every template written for those engines is included too. The BPMN studio and Weave, which have engines of their own, start on Starter. AI features, such as describing a diagram, AI conversion and TikZ export, need AI on your plan. See Plans and what they include.

The Studio's engine library, group by group

The library lists 108 engines in these groups. Each name links to its reference page.

Flow & UML

Flow systems

Risk & reliability

Quality & control

Architecture

Charts & data

Schemas & layouts

Research & analysis

Engineering & physical

Domain-specific

More

Engines outside the Studio's library

For the engines grouped by subject, with syntax and examples, see the engine reference pages: Software and architecture, Business, strategy and planning, Process, operations and quality, Charts and data visualisation and Maths, science and academic.

Tips

• Search for the job, not the engine. Type what you are drawing ("org chart", "critical path", "threat model") or the tool you are leaving ("Visio", "Minitab") into the engine search.
• Start from a template. An engine's templates are the fastest way to learn its syntax. Open the Templates tab, or see Starting from a template.
• Prefer engines that check, for work that matters. A sequence, state machine, schedule or risk model that checks itself catches the mistakes a drawing hides.
• Keep confidential sources in flowss. Engines drawn inside flowss or in your browser never send your source to an outside service.
• Convert rather than switch. Clicking another engine replaces your source with its starter. Convert to another engine… carries your diagram across.
• Pick Mermaid for maximum portability. Mermaid source renders in many other tools and documentation sites, and it has the richest click-to-edit support in the Studio.

Limits and known constraints

• One engine per figure. To combine notations, use several figures, or compose them on a canvas such as Weave.
• Switching resets the source. Clicking an engine row replaces the source with that engine's starter. Undo with ⌘Z, or use Convert to another engine… instead.
• Outside services need a connection. The twelve engines drawn by an outside service need a connection, send their source to that service, and are subject to daily render limits and source-size limits.
• The render API draws only built-in engines. It cannot draw engines that render in your browser or through an outside service.
• Instant conversion covers a few pairs. Other conversions use AI, which needs AI on your plan and may not carry every detail. Check the result.
• BPMN and Weave live elsewhere. They are not in the Studio's engine list, and their studios start on Starter.

Troubleshooting

Related pages

• The full engine catalogue
• The Studio editor
• Starting from a template
• Importing and converting
• Flow-systems analysis in Studio
• Software and architecture engines
• Business, strategy and planning engines
• Process, operations and quality engines
• Charts and data-visualisation engines
• Maths, science and academic engines
• Embedding and the render API
• Plans and what they include