Diagram as Code: Turning BPMN Process Documentation into AI-Ready Mermaid

Intro:
Many organisations have built a large volume of process documentation over the years using Visio diagrams, PDF exports, and BPMN process models.
These documents remain valuable sources of process knowledge. They capture roles, systems, activities, handovers, decisions, controls, exceptions, and end-to-end business flows. But they are primarily designed for people to read as static visual artefacts.
When we try to bring this content into an agentic experience—for example, to enable an AI agent to explain a process, answer questions about responsibilities, identify decision points, or generate supporting documentation—the format becomes more challenging.
A PDF or Visio diagram can be interpreted by a generative AI model, but it is not always easy to reliably extract and preserve the underlying process logic. Details such as branching conditions, parallel activities, ownership, notes, and exceptions can be missed, merged, or inferred incorrectly.

Generative AI works particularly well with the idea of diagrams as code: a structured, text-based representation of a diagram that can be read, versioned, compared, reviewed, and regenerated.
This is where Mermaid is useful.
Mermaid enables process interactions to be represented as readable code. For example, a sequence diagram can define participants, actions, alternative paths, parallel activities, and process notes in a format that both people and AI agents can work with:

The goal is not to replace established BPMN, Visio, or PDF documentation. Instead, it is to create an AI-friendly, maintainable representation of approved process logic—one that can support agentic experiences while remaining traceable to the original process source.

To explore this, I contributed the skills-bpnm-seq skill. It supports the conversion and evaluation of business-process content as Mermaid sequence diagrams, with a particular focus on preserving process fidelity rather than allowing AI to introduce unvalidated logic.

The challenge: readable does not always mean reliable

A typical process document may describe:

• Business roles and system participants
• Sequential activities
• Parallel activities
• Decision points and alternative routes
• Mandatory data requirements
• Regional exceptions
• Downstream integrations
• Settlement or reconciliation outcomes
• References to related procedures

A Mermaid sequence diagram can represent much of this clearly using constructs such as:

• participant for business teams and systems
• ->> for actions and system interactions
• alt / else for decision logic
• par for activities that can occur in parallel
• Note over for process context, rules, and clarifications

Setup:
This capability is available through the new Copilot Studio agent experience, which is a production-ready preview. Skills can be uploaded as a .zip package containing SKILL.md and optional supporting files such as scripts, templates, and reference documents. Skills overview for agents

Download or clone the skill from the repository:
Package the contents of the skill folder into a ZIP file. The ZIP should have SKILL.md at its root, with the supporting folders retained:

skills-bpnm-seq.zip
├── SKILL.md
├── scripts/
│   └── ...
├── templates/
│   └── ...
└── references/
    └── ...

Testing the Skill with Real Process Documentation:
Once the skill was available in Copilot Studio, I tested it with three business-process scenarios.
For each scenario, I uploaded the relevant PDF process document and/or Visio (.vsdx) process map, then asked the agent to generate Mermaid sequence-diagram code. The agent output was treated as a proposed representation of the process—not automatically as the approved process diagram.

The three scenarios were:

• Third-Party Customer Setup - Wholesale, concessions, consignment, and other third-party customer creation, including Reltio, Finance, Operations, mandatory attributes, and credit management.
• Month-End / Year-End Financial Period Close - Parallel close activities, year-end decision logic, period closure, reopening, reconciliation, and completion review.
• Credit Note Receipt and Management - Coupa approval, D365 posting, invoice settlement routes, local inventorised SPM, and physical versus virtual return paths.

Process team source documentation
            |
            v
Copilot Studio + skills-bpnm-seq
            |
            v
Proposed Mermaid sequence diagram
            |
            v
AI Builder LLM-as-a-Judge comparison
            |
            v
Process-owner validation
            |
            v
Approved Mermaid diagram

The original process-team output remains the authoritative baseline. The skill and the AI Builder evaluation act as an acceleration and quality-review layer: they help identify missing content and make diagrams easier to maintain as code, without allowing AI-generated interpretation to silently become approved process logic.

Using AI Builder as an LLM-as-a-Judge
To make the assessment more structured, I used AI Builder to simulate an LLM-as-a-Judge evaluation. Concept example

For each test case, the judge received two inputs:

1. The original PDF or Visio process documentation, treated as the source of truth; and
2. The Mermaid sequence-diagram output generated by the Copilot Studio agent using the skills-bpnm-seq skill.

The judge was asked to compare the artefacts across a defined set of characteristics:

This evaluation method is useful because it separates two questions that are often confused:

• Is the Mermaid diagram readable and well structured?
• Is it faithful to the approved business process?

A diagram may perform well on readability while still being unsuitable as controlled process documentation if it adds logic that the process team has not approved.

The original process-team output remains the authoritative baseline. The skill and the AI Builder evaluation act as an acceleration and quality-review layer: they help identify missing content and make diagrams easier to maintain as code, without allowing AI-generated interpretation to silently become approved process logic.

The challenge is not simply converting a diagram into code. It is ensuring that the coded representation preserves the intent, controls, and ownership defined by the process team.

Closing Thoughts:
Process documentation does not need to remain trapped in static Visio files and PDF exports.

By representing approved BPMN process logic as Mermaid code, teams can create a versionable, maintainable, and AI-friendly process asset. This makes it easier to use process knowledge in agentic experiences—for example, to explain end-to-end flows, answer questions about handovers and decision points, support training content, or assess the impact of process changes.

The skills-bpnm-seq skill demonstrates one practical route from traditional process artefacts to diagram-as-code. The Copilot Studio agent can accelerate the conversion, while an LLM-as-a-Judge approach can help identify missing steps, terminology gaps, and unclear exceptions.
But the evaluation also reinforced an important boundary:

AI can propose, compare, and clarify process logic. Process owners must remain accountable for approving it.

The best outcome is not an AI-generated diagram that looks more detailed than the original. It is a trusted Mermaid representation of the approved process, enhanced only where additional detail can be traced back to the original PDF, Visio model, or validated process-owner input.

My recommended approach is therefore:

• Keep the approved process documentation as the source of truth.
• Use Mermaid as the AI-friendly diagram-as-code layer.
• Use Copilot Studio and skills to accelerate generation and analysis.
• Use LLM-as-a-Judge evaluation to highlight potential gaps, not to make process decisions.
• Require process-owner validation before publishing any generated or amended diagram.