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.

Useful details:

• The process name at the top stays linked to the repository entity.
• BPMN changes save when you close the editor.
• BPMN is best for process behavior and handoffs. Reusable enterprise-architecture relations still belong in repository-linked entities and relations.

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.