Use Mermaid as context for an LLM: a worked example

Mermaid source can help a large language model (LLM) answer a system-specific question because it supplies explicit component names and directed relationships as text. In this worked example, incident facts alone support a broad failure boundary between webhook acknowledgement and the creation queue. Adding a verified Mermaid flowchart to the same prompt narrows that boundary to the receiver, stage matcher and enqueue handoff, and it gives the investigation an evidence-based order.

The diagram does not make the answer true. It makes relevant system structure available for inspection. Logs, code and configuration must still confirm the cause.

This article uses a fictional Pipedrive-to-Jira incident and two edited representative responses. They are constructed teaching fixtures, not outputs from a named model or proof that adding Mermaid always improves an answer. You can download both prompts and repeat the comparison with an LLM your organization permits you to use.

Use the same question and incident facts in both prompts

The fictional incident has five observations:

Both runs ask the exact same question:

Based only on the supplied information, identify the narrowest supported
failure boundary, give the first three checks in order, and separate observed
facts from assumptions.

The instructions also tell the model to use only supplied information, avoid inventing system behavior and state when the evidence cannot distinguish between causes. That output contract matters: Mermaid context is easier to misuse when the question invites unconstrained guessing.

Run 1: ask without Mermaid context

The first prompt contains the question, response format and five incident observations. It says nothing about the implementation between the receiving endpoint and queue.

Download the prompt without Mermaid context.

An evidence-respecting response can still make useful progress:

Supported boundary: The failure is after the external endpoint acknowledged the event and before a creation job appeared in the queue. The supplied facts do not identify the internal step.

First three checks: (1) correlate evt-204 with receiver logs; (2) inspect any filtering, validation or field-mapping decision applied to that event; (3) inspect the enqueue attempt and result.

Observed facts: HTTP 200, Won stage, no queue job, no link record and no Jira issue.

Assumptions and unknowns: HTTP 200 may only mean receipt. The internal routing, matcher and enqueue behavior were not supplied. No evidence shows that Jira received a request.

This is a competent answer. It uses the empty queue to avoid starting with a broad Jira API investigation. Its limit is structural: “filtering, validation or field mapping” is a category of possible behavior, not a component known to exist in the supplied system.

Add the verified Mermaid source as relevant context

Now add the accepted system path to the prompt as Mermaid text:

flowchart LR
  accTitle: Pipedrive to Jira issue creation path
  accDescr: A Pipedrive deal update reaches a webhook receiver, passes a Won-stage mapping decision, enters a creation queue, and is processed by a Jira creation worker that stores the resulting issue key.
  source["Pipedrive"]
  receiver["Webhook receiver"]
  matcher{"Stage mapping matches Won?"}
  queue[("Creation queue")]
  worker["Jira creation worker"]
  jira["Jira create-issue API"]
  links[("Deal–issue links")]
  ignored["No action"]

  source -->|deal.updated| receiver
  receiver -->|Validated event| matcher
  matcher -->|Yes: enqueue creation| queue
  matcher -->|No: stop| ignored
  queue -->|Creation job| worker
  worker -->|Create issue| jira
  jira -->|Issue key| worker
  worker -->|Store deal ID and issue key| links

Download the Mermaid source and rendered SVG. Mermaid's flowchart reference explains how nodes, directed edges and edge labels are represented in this text.

Stable IDs such as receiver, matcher and queue give the model concise references. Readable labels explain their roles. Edge labels add the event or action that connects them. The source is more useful than a list of component names because it also encodes sequence and direction.

The prompt explicitly identifies the diagram as verified current context while warning that it describes possible routing, not evidence that a step ran during this incident. Only add that label after a knowledgeable owner has checked the source. If the diagram is a proposal or an incomplete view, say that instead.

Run 2: ask the same question with Mermaid

The second prompt preserves the original instructions, observations, question and response format. The Mermaid block is the only added evidence.

Download the prompt with Mermaid context.

A response grounded in both inputs can be more concrete:

Supported boundary: The unresolved segment starts at the webhook receiver and ends at the receiver-to-matcher-to-queue path. HTTP 200 shows acknowledgement at the receiver boundary; the missing queue job shows that the documented path did not reach the queue. The evidence does not distinguish receiver validation, matcher evaluation or enqueue failure.

First three checks: (1) find evt-204 in receiver logs and confirm whether validation passed the event to matcher; (2) inspect the matcher's input and recorded branch decision, including the value or ID compared with Won; (3) inspect the matcher → queue enqueue attempt and result for evt-204.

Observed facts: Pipedrive received HTTP 200; the deal was visibly Won; no matching queue job, link record or Jira issue was found. The verified diagram documents a receiver, stage matcher and creation queue in that order.

Assumptions and unknowns: HTTP 200 does not prove validation or matching. The visible stage label may differ from the payload value used by the matcher. No supplied log identifies the failing step. The worker, Jira API and link-store write are downstream of the empty queue, so they are lower-priority checks unless other evidence shows a job existed.

The answer still stops short of naming a root cause. The improvement is a narrower, auditable investigation: each check corresponds to a documented node or edge, and downstream checks are deferred for a stated reason.

Compare what the Mermaid context changed

Download the comparison as CSV.

The baseline and diagram-assisted responses reach the same high-level conclusion. Mermaid improves specificity and traceability in this fixture. That distinction matters: a more detailed answer is valuable only when its details come from accepted context rather than invention.

Why Mermaid can be useful LLM context

When you paste Mermaid source, the model receives ordinary structured text. It can refer to IDs, labels and connections without needing to infer the diagram from pixels. For a focused question, that structure can provide:

1. Named entities: exact component IDs reduce vague references such as “the middle service.”
2. Directed relationships: arrows constrain which handoffs are documented.
3. Decision branches: labels such as Yes: enqueue creation and No: stop expose alternative paths.
4. A bounded scope: the model can identify what the view includes and state what remains absent.
5. Traceable recommendations: a reviewer can map each suggested check back to a node, edge or incident fact.

OpenAI's prompt engineering guidance recommends supplying relevant context and separating prompt sections clearly. Its model optimization guidance also treats reference text as one way to improve context, while warning that irrelevant or incorrect context can reduce quality. Those principles support testing this method; they do not guarantee the same effect for every model, diagram or task.

Use a reusable prompt structure

Keep facts, instructions and diagram source in separate labeled sections:

TASK
[State the decision or question.]

RULES
- Use only supplied information.
- Cite the node, edge or evidence item supporting each conclusion.
- Separate observations, inferences and unknowns.
- Do not treat successful rendering as factual validation.

OBSERVATIONS
[Add current logs, measurements or reviewed facts with IDs and times.]

VERIFIED SYSTEM CONTEXT
[Paste the smallest current Mermaid view that covers the task.]

RETURN
1. Direct answer
2. Evidence used
3. Ordered checks or actions
4. Assumptions and missing evidence

Use the smallest view that answers the question. A repository-wide diagram can consume context while hiding the few relevant relationships. If a component name is ambiguous, clarify it in the Mermaid label or an adjacent evidence note rather than asking the model to infer local terminology.

What Mermaid cannot tell the model

A flowchart is a claim about a system, not live system evidence. This example does not tell the model:

• whether the receiver returns HTTP 200 before or after validation;
• the event schema or stage identifier used by the matcher;
• whether queue writes are retried or transactional;
• whether the queue observation covered the correct environment and time;
• the current configuration, deployment revision or relevant log entries.

Add those facts only when you can verify them. A Mermaid render also checks a different property from system accuracy. Mermaid documents that mermaid.parse checks whether the graph definition is syntactically valid without rendering it. Parsing and rendering cannot confirm that the graph matches production behavior.

Before sharing internal source with an external LLM service, remove secrets, personal data and unnecessary customer identifiers, and follow your organization's data-handling rules. A sanitized diagram can preserve the relationships needed for analysis without exposing production values.

Verify the answer as a hypothesis

Review every model claim against the incident record and accepted diagram. Then confirm the proposed boundary with logs, code or configuration. If runtime evidence contradicts the Mermaid source, update the system record through its normal review process; do not force the incident to fit an outdated diagram.

If you are creating the diagram from written rules, start with the requirements-to-Mermaid workflow. Before trusting generated architecture, use the AI-generated diagram review. For the real integration pattern behind this fictional scenario, the Pipedrive-to-Jira webhook checklist separates delivery, trigger, mapping and creation evidence.

If your team keeps Mermaid source in Confluence, Diagram Lens provides a source editor and rendered preview for reviewing that text. It does not verify the architecture or the LLM's conclusion. Keep the diagram, incident facts and checked conclusion as separate evidence.