Mermaid vs BPMN: Differences, Limitations and When to Migrate

Mermaid can illustrate business processes, but it does not implement the full BPMN 2.0 notation or execution semantics. Use Mermaid for readable, text-based process explanations. Use BPMN when formal events, participant boundaries, gateway behavior or executable workflow rules need to be part of the model.

A Mermaid flowchart often begins as the right answer: someone writes a few steps, the team corrects them, and a process that lived in people's heads becomes visible. Trouble starts when the team asks the picture to do a different job.

Now the process must wait for messages, distinguish manual work from automated work, handle timeouts, coordinate several participants or run in a workflow engine. More boxes and arrows can make the flowchart look complete without defining what those behaviors mean.

Switch from Mermaid to BPMN when the process needs formal behavior rather than only a clear explanation. Keep Mermaid when the purpose is communication, lightweight review and documentation close to prose. Consider BPMN when events, gateway behavior, participant boundaries or executable workflow semantics materially affect the outcome.

Migration is not a syntax conversion. Preserve the original, verify its business rules, then model those rules explicitly in a BPMN tool chosen for the process's real destination.

Download the Mermaid-to-BPMN migration checklist before starting. Use it to track scope, semantics, mapping, validation and ownership without treating the migration as a one-click conversion.

This article provides a migration method, not deployable BPMN XML. Its fictional Mermaid example was checked locally with Mermaid 11.16.0. The candidate BPMN mappings deliberately remain unresolved until a process owner and a qualified modeler confirm their meaning in the intended BPMN tool or engine.

Use the job of the diagram as the decision test

The current Mermaid syntax reference lists Mermaid's supported diagram types; BPMN is not one of them. A Mermaid flowchart can resemble a process model and communicate one well, but adding circles and diamonds does not give it BPMN semantics.

BPMN 2.0.2 is maintained by the Object Management Group. BPMN defines a much richer process language than a generic flowchart. That richness is valuable when it answers a real operating need; it is overhead when the team only needs to explain five steps on a Confluence page.

Five signs the Mermaid diagram has reached its boundary

1. People disagree about what an arrow means

One person reads an arrow as “this happens next.” Another reads it as a message sent to a separate company. A third thinks it means an automated trigger. BPMN distinguishes sequence flow within a process from communication between participants.

2. Waiting changes the process

The process waits for a corrected document, a customer response, a timer or a payment event. The wait is not just a note; it determines whether the process continues, escalates or ends.

3. A diamond no longer means one kind of decision

One branch chooses exactly one route, another starts two routes together, and another waits to see which external event happens first. BPMN has different gateway types because those behaviors are not interchangeable. Camunda's gateway overview gives a concise product-specific explanation of exclusive, parallel, event-based and inclusive gateways.

4. The model will be executed

An executable model needs engine-specific properties, supported element types, expressions, job workers and deployment rules. Even tools that use BPMN 2.0 can support different executable subsets. Camunda, for example, tells modelers to create diagrams for the engine on which they will run and publishes a separate BPMN coverage table.

5. Exceptions are more important than the happy path

Timeouts, cancellations, error handling, compensation and non-interrupting reminders can determine whether the process is safe. A Mermaid exception branch can explain the intention. BPMN is the stronger candidate when the model must define how the running process reacts.

Mermaid flowchart to BPMN element mapping

A Mermaid shape can suggest a BPMN element, but its appearance does not establish BPMN behavior. Use this mapping table to generate review questions, not to convert shapes mechanically:

The right-hand question is the migration work. A converter can copy geometry. It cannot reliably decide the business semantics that were never recorded.

What Mermaid cannot represent faithfully

Mermaid can label or style a node so that it resembles a BPMN symbol. The renderer still treats the result as a flowchart, so it cannot validate or preserve the formal behavior behind these BPMN concepts:

This does not make Mermaid unsuitable for process documentation. It means that a visual convention must not be mistaken for a validated BPMN model. If one of these behaviors affects the business outcome, record it as a requirement and model it in the target BPMN environment.

Before migration: a Mermaid supplier invoice flow

This fictional flowchart is useful for a business conversation. Accounts Payable checks an invoice, requests corrections when needed, routes high-value invoices to a manager, and posts accepted invoices.

flowchart TD
  accTitle: Fictional supplier invoice review
  accDescr {
    Accounts Payable checks a received invoice. Incomplete invoices return to the supplier.
    Complete invoices below the approval threshold are posted. Higher-value invoices require manager approval; refused invoices return for correction.
  }

  invoice_received["Invoice received"]
  check_invoice["Accounts Payable checks invoice"]
  information_complete{"Required information complete?"}
  supplier_correction["Supplier corrects invoice"]
  approval_required{"Manager approval required?"}
  manager_review["Manager reviews invoice"]
  approved{"Approved?"}
  post_invoice["Finance system posts invoice"]
  invoice_recorded["Invoice recorded"]

  invoice_received --> check_invoice
  check_invoice --> information_complete
  information_complete -->|"No: correction required"| supplier_correction
  supplier_correction -->|"Corrected invoice"| check_invoice
  information_complete -->|"Yes: complete"| approval_required
  approval_required -->|"No"| post_invoice
  approval_required -->|"Yes"| manager_review
  manager_review --> approved
  approved -->|"No: correction required"| supplier_correction
  approved -->|"Yes"| post_invoice
  post_invoice --> invoice_recorded

Download the invoice Mermaid source, the migration worksheet and the migration checklist.

The flowchart answers the meeting question, “What happens to an invoice?” It deliberately does not answer several BPMN questions:

• Does an email from the supplier start the process, or does a member of Accounts Payable create a case?
• Is the supplier a separate participant?
• Does “Supplier corrects invoice” mean the company waits for a message?
• Can the process time out while waiting?
• Is posting an automated service task or a human action in the finance system?
• Does a refusal end the current review or loop within the same process instance?

Those are not formatting details. They determine the target model.

Migrate in seven controlled steps

Step 1: freeze and label the Mermaid source

Keep the last accepted Mermaid source as migration evidence. Add its owner, review date, scope and status. Do not silently replace the page while the BPMN model is still being debated.

Record whether the diagram describes the current process, a proposed process or a mixture. Split mixed views before migration so the target model does not accidentally turn a proposal into current-state behavior.

Step 2: write a short process contract

Use prose to record:

• the business outcome;
• what starts one instance;
• what ends it;
• participants and their boundaries;
• main decisions and their owners;
• messages, timers and important exceptions;
• whether the target is descriptive or executable.

For the invoice example, “Invoice received” is too vague for an executable start condition. The process owner must choose an observable trigger.

Step 3: inventory nodes and arrows

Put every Mermaid node and relationship into a worksheet. Preserve the stable IDs. For each arrow, record the business fact supporting it and whether it represents sequence, communication or an unresolved relationship.

This two-way check catches both omissions and additions: every accepted Mermaid relationship should have a disposition, and every BPMN element should have an accepted requirement or a clearly marked new design decision.

Step 4: identify participants before lanes

A supplier and the buying company may be separate BPMN participants, commonly represented as pools. Accounts Payable and the approving manager may be responsibilities inside the company's process, commonly represented as lanes.

Do not turn every Mermaid subgraph into a pool. In BPMN, pools, lanes and subprocesses answer different questions. Camunda's BPMN primer notes that pools and lanes sit at the top-level process or collaboration level in its modeling context.

Step 5: choose tasks, events and gateways by behavior

Use verbs for tasks: “Check invoice,” “Review invoice,” “Post invoice.” Decide who or what performs each task.

Use events for things that happen or are awaited. Camunda's event guide distinguishes start, intermediate and end events, as well as catching and throwing behavior. That guide describes Camunda's supported execution semantics; confirm the rules in your chosen BPMN environment.

Use gateways only when flow behavior needs them. For the invoice example, “Required information complete?” and “Manager approval required?” are candidates for exclusive gateways if exactly one outgoing condition is selected. A parallel gateway would mean something different, not simply “a more important decision.”

Step 6: model the normal path, then add one exception at a time

First model one complete invoice below the approval threshold. Walk it from the start event to the end event. Then add manager approval. Then add supplier correction. Add timers or errors only when the process contract supports them.

This order prevents the target model from becoming a wall of boundary events before anyone has confirmed the main route.

Step 7: validate the model at three levels

1. Business validation: process owners can trace normal, refused and corrected invoices.
2. Notation validation: a BPMN reviewer checks event, task, gateway, participant and flow choices.
3. Execution validation: if applicable, the target platform validates its supported elements, required properties and runtime behavior.

A model can be valid BPMN but unsupported by a particular engine. It can also deploy successfully while implementing the wrong business rule. Keep these checks separate.

After migration: the reviewed BPMN design

Assume the process owner confirms that a supplier's invoice message starts the process, the supplier is external, Accounts Payable and the manager are internal responsibilities, and posting is automated. The migration then changes more than the shapes:

The resulting happy path is: supplier message → message start event → check-invoice user task → completeness gateway → approval gateway → optional manager-review user task → approval-result gateway → post-invoice service task → end event. The incomplete or refused route sends a correction request to the supplier, waits for a corrected-invoice message and then returns to the check task.

That is the after design for this worked example, but it is not deployable BPMN XML. A BPMN modeler must still create it in the target tool, validate the notation and confirm any engine-specific execution properties. If the assumptions above are not true, the target model must change.

Use the element-level review table below to retain traceability from the original Mermaid source:

The worksheet contains these rows and columns for evidence, owner, target participant and engine-support checks. Replace the example decisions with your verified answers.

Use an LLM as a migration assistant, not the process owner

An LLM can help inventory Mermaid nodes, format a mapping table, spot an arrow with no recorded disposition or draft questions for a workshop. It should not silently decide that a gateway is exclusive, invent a timeout or choose an executable task type.

Use a prompt that exposes uncertainty:

You are preparing a Mermaid-to-BPMN migration review.

Inputs:
1. accepted Mermaid source;
2. process contract with requirement IDs;
3. target platform's supported BPMN elements.

For each Mermaid node and edge:
- copy its exact ID and label;
- cite the requirement that supports it;
- suggest zero or more candidate BPMN elements;
- explain what business question must be answered before choosing;
- mark unsupported or ambiguous mappings as unresolved.

Do not produce deployable BPMN XML.
Do not invent events, task types, participants, conditions or timeouts.
Return a review table, not a final process model.

The human-oriented process contract and the structured inventory serve the LLM too. The model's output is a workshop aid. The accepted BPMN model remains a decision by process owners and qualified modelers, validated in the target tool.

Keep Mermaid after the migration when it still has a job

Moving to BPMN does not require deleting every Mermaid diagram. The two notations can serve different readers:

• a small Mermaid overview can introduce the process on a general documentation page;
• the BPMN model can define formal behavior for analysts or execution;
• a short table can state which Mermaid overview corresponds to which governed BPMN model and version.

Do not maintain two independent sources of truth. Name the authoritative model, define who updates the overview, and include a review trigger when the BPMN process changes.

Frequently asked questions

Does Mermaid support BPMN 2.0?

No. Mermaid's official syntax reference does not list BPMN as a supported diagram type. A Mermaid flowchart can illustrate a business process and imitate some familiar shapes, but it does not provide the complete BPMN 2.0 notation, formal execution semantics or BPMN XML interchange. Use a BPMN-capable modeler when those properties are requirements.

Can Mermaid be converted to BPMN automatically?

Only the visible structure can be mapped automatically with reasonable confidence. A reviewer must still decide what starts the process, which arrows are messages, how gateways behave, whether tasks are human or automated, and how exceptions work. Treat generated BPMN as a draft for validation, not as a faithful conversion.

Should the Mermaid diagram be deleted after migration?

Not necessarily. Keep a simple Mermaid overview when it helps general readers, but identify the governed BPMN model as the authoritative source and define how the overview will be kept in sync.

If people and AI assistants both use the overview, follow Mermaid diagrams for humans and LLMs to preserve clear labels, stable IDs and explicit status. For ownership and review cadence, use the Mermaid diagram governance guide.

Diagram Lens can support the lightweight Mermaid side of this documentation set in Confluence. It is not a BPMN modeler or workflow engine. Once formal BPMN behavior becomes the requirement, choose and validate a tool built for that purpose.