Mermaid and BPMN diagrams

Caplo supports Mermaid and BPMN when text-based or process-specific notation is a better fit than free-form architecture shapes.

Mermaid diagrams

Use Mermaid for compact diagrams that are easier to maintain as text, such as sequence diagrams, ER diagrams, flowcharts, or lightweight dependency views.

Caplo can render Mermaid syntax broadly, but repository-aware extraction currently focuses on:

• Sequence diagrams
• ER diagrams

That means these two Mermaid styles are the best fit when you want Caplo to recognize referenced repository entities and derive read-only relations from the diagram.

What is special about Mermaid in Caplo

In Caplo, Mermaid is not just a visual diagram format. When Caplo can match Mermaid participants or entities to repository items, the Mermaid relations become part of Caplo's repository-connected analysis model.

That means Mermaid-derived relations can contribute to graph exploration and reporting, even though they remain derived relations instead of normal editable repository relations.

Mermaid examples

Sequence example:

sequenceDiagram
    participant App as Customer Portal
    participant API as Integration API
    participant ERP as ERP

    App->>API: Create order
    API->>ERP: Sync order

ER example:

erDiagram
    APPLICATION ||--o{ INTERFACE : exposes
    APPLICATION ||--o{ DATA_OBJECT : reads

Editing Mermaid in Caplo

Double-click a Mermaid shape to open the full editor. The code editor is on the left and the rendered preview is on the right.

Useful details:

• Use the built-in syntax link in the editor for Mermaid reference material.
• Save the Mermaid editor when you want the diagram, detected entities, and derived relations to update.

Pro tip: mention repository entities directly

Type @ while editing Mermaid to mention existing repository entities directly in the editor. This helps Caplo match the Mermaid diagram to the right repository items.

Derived relations

When Caplo can map Mermaid participants or entities to existing repository items, it derives read-only relations from the Mermaid shape.

These derived relations are:

• visible in Caplo where the diagram is used
• useful for exploration, graph-based analysis, and reporting
• not the same as normal repository relations that you manage directly

This is one of the Caplo-specific advantages of Mermaid support: Mermaid relations do not stay trapped inside the text block. They can influence repository-connected analysis and report traversal as long as Caplo can resolve the referenced entities.

If you want a reusable relation that exists independently from the Mermaid diagram, model it explicitly with linked shapes and relations elsewhere in Caplo.

For general Mermaid syntax, see the Mermaid docs.

BPMN diagrams

Use BPMN for business processes that need process notation with tasks, events, gateways, pools, and lanes.

In Caplo, BPMN lives in a full-screen editor backed by a linked Process entity. Double-click a BPMN shape to open the editor, then use the BPMN modeler to draw or refine the process flow.

What is special about BPMN in Caplo

In Caplo, BPMN is not just a standalone process diagram. When you link repository entities to BPMN tasks, lanes, or pool participants, Caplo derives read-only relations from those tagged entities to the linked Process.

That means BPMN-derived relations can contribute to graph exploration and reporting, even though they remain derived relations instead of normal editable repository relations.

Editing BPMN in Caplo

Useful details:

• The process name at the top stays linked to the repository Process entity. You can rename, relink, or create that entity from the editor header.
• BPMN changes autosave while you edit and flush when you leave the editor tab.
• BPMN is best for process behavior and handoffs. Reusable enterprise-architecture relations still belong in repository-linked entities and relations.

Link repository entities to BPMN elements

You can tag individual BPMN elements with repository entities:

1. Select a task, lane, or pool participant in the BPMN editor.
2. Open the context pad and choose the link icon to search for a repository entity.
3. Use the unlink icon to clear a tag when needed.

Tagged elements show repository entity styling directly on the diagram, so process steps stay visually connected to applications, actors, data objects, and other repository items. Tagged tasks keep their process-step name in the task body and show the linked entity in a header band above it.

Process entity vs. element tags:

• The diagram header links the whole BPMN shape to one Process entity.
• Element tags connect specific tasks, lanes, or participants to supporting repository entities.

Derived relations

When you tag BPMN elements with repository entities, Caplo derives read-only relations from each tagged entity to the linked Process entity.

These derived relations are:

• visible in the entity Relations tab and graph explorer
• useful for exploration, graph-based analysis, and relation-path reports
• not the same as normal repository relations that you manage directly

If you want a reusable relation that exists independently from the BPMN diagram, model it explicitly with linked shapes and relations elsewhere in Caplo.

Pro tip: tag tasks with real applications

Link BPMN tasks to applications, actors, or data objects from your repository. That makes Process-to-Application paths appear in graph exploration and reporting without redrawing the process elsewhere.

Import BPMN files

You do not need to redraw an existing process from scratch:

• Drop a .bpmn file onto the canvas, or
• Paste BPMN XML text onto the canvas.

Caplo creates a new BPMN diagram shape, opens the editor, and preserves any Caplo entity bindings already stored in the XML. Invalid BPMN files show an error message.

Pro tip: import existing BPMN instead of redrawing

If your team already has BPMN files from another tool, paste or drop them onto the canvas for the fastest import path.

If your team is new to BPMN notation, the bpmn.io documentation is a good reference for the modeling basics.

Choosing between diagram types

• Use architecture shapes for reusable enterprise architecture objects.
• Use Mermaid for compact text-first diagrams, especially sequence and ER views.
• Use BPMN for process modeling.
• Use Draw mode for early sketches, comments, and visual explanation.

Keep each diagram focused. Mixing styles is useful when it clarifies the story, but it can become hard to read if one canvas tries to do everything.