Analyzing Diagrams With AI: Turning an Architecture Picture Into Requirements and Gaps

Analyzing a diagram with AI is the opposite task to drawing one. You hand a model the picture somebody else drew and ask what it does not say: which arrow has no failure path, which box has no owner, which gateway has no branch for the unexpected condition. Extract the diagram to structured text first, then diff it against the API contract and the code. Every contradiction you find is a requirement nobody has written.

Every project starts with a diagram you were handed. A PNG in a Confluence page from eighteen months ago, a BPMN file exported from a modeller nobody has opened since, a whiteboard photograph in a Teams chat. You are expected to write requirements against it, and the honest position is that you do not know how much of it is still true.

Generating diagrams with AI is the well covered half of this. This is the other half, and it is the half that finds defects. It is stage four of the requirements to UAT pipeline. If you want the systems analysis toolkit that sits behind it, it is in The Technical Skills Guide for BAs.

Why does analysis start by converting the picture to text?

Because you cannot diff a picture, validate a picture, or run a rule over a picture.

A multimodal model reads a reasonable architecture diagram accurately. The problem is not comprehension, it is that a conversational answer about an image leaves you nothing to check. Extract to structured text and every subsequent step becomes mechanical.

Extract the attached diagram into YAML. Transcribe only. Do not
interpret, do not add anything that is not drawn or labelled.

participants:   every box, with its exact label and any subtitle
edges:          from, to, label, style (solid/dashed/dotted), direction
groups:         swimlanes, boundaries, or dotted-line groupings
annotations:    every note, legend entry, and free-floating text
unreadable:     anything you cannot read, described by position

Rules:
- Use the label exactly as drawn, including inconsistent capitalisation.
- If an arrow has no label, write label: NONE. Do not guess its purpose.
- If you cannot tell which way an arrow points, put it in unreadable.
- Do not add participants that "should" be there.

The transcription discipline is the whole trick. Without it a model helpfully labels an unlabelled arrow “sends payment request”, and you have just invented a requirement from a line on a picture. With it, label: NONE appears fourteen times in a typical architecture diagram, and those fourteen unlabelled arrows are your first finding: nobody knows what is on that wire.

The unreadable section is equally useful. A model saying it cannot read the text in the small box bottom right is an accurate report about a diagram that a human reader would have silently skipped.

The nine questions a diagram never answers

Now run the interrogation. Five questions per arrow, four per box. This is where the requirements come from.

For each edge in the extracted YAML, answer these five questions using
ONLY the diagram and the attached artifacts (openapi.yaml, events.md,
requirements/functional.yaml). Where the answer is not in any of them,
write NOT SPECIFIED and mark it as a gap.

1. FAILURE: what happens if this call or message fails?
2. TIMEOUT: how long does the caller wait, and what does it do then?
3. RETRY: can this be retried safely? Is the receiver idempotent?
4. DUPLICATE: can the receiver get this twice? What does it do?
5. NOTIFY: who is told when this fails, and how?

For each participant, answer these four:
6. OWNER: which team owns this component?
7. STATE: what state does it hold, and is it the system of record for it?
8. OUTAGE: what happens to the flow when this is unavailable?
9. ORDER: does this component depend on receiving things in order?

Output a table. One row per gap. Nothing else.

Run that against a real architecture diagram with fourteen arrows and you get between thirty and sixty NOT SPECIFIED rows. That is not a failure of the diagram, it is what diagrams are: a picture of the happy path. The rows are your requirements backlog, and the useful move is to rank them by what would actually hurt.

Gap	Why it ranks high
Async hop with no duplicate handling	Every message broker delivers at least once. This will happen, not might.
External call with no timeout	One slow dependency takes down the whole flow. Classic cascading failure.
Retry against a non-idempotent endpoint	Produces duplicate payments, duplicate refunds, duplicate anything.
Component with no named owner	Nobody will fix it at 03:00, and nobody will approve a change to it.
Order-dependent consumer with a partitioned topic	Works in test with one message, fails in production under load.

The duplicate question deserves special attention in event-driven systems, because it is the one that separates a diagram that was drawn from one that was thought about. The detail is in idempotency testing and event-driven requirements.

Reconciling the diagram against the system that exists

The gaps above are things the diagram does not say. This section is about the things it says that are no longer true, which is a different and more dangerous category.

Three artifacts, three diffs:

Diagram against the API contract. Extract every call in the OpenAPI file and every edge in the diagram, and compare.

You have two lists:
A: edges extracted from the architecture diagram
B: operations from openapi.yaml plus events from events.md

Produce three sections:
- IN DIAGRAM, NOT IN CONTRACT: an arrow exists with no matching
  operation or event. Either the diagram is stale or the integration
  is undocumented.
- IN CONTRACT, NOT IN DIAGRAM: an operation or event nobody drew.
  For each, say what it appears to do based on its path and schema.
- STYLE MISMATCH: drawn as a synchronous call but published as an
  event, or the reverse.
Quote the evidence for every row.

The third section is the one that changes your requirements. A synchronous call and an asynchronous event carry different rules about ordering, retry, failure visibility, and user experience. A diagram that draws the settlement notification as a straight arrow when it is actually a Kafka publish will produce a functional specification that promises the customer a result the system cannot deliver synchronously.

Diagram against the code. If you can read the orchestrating service, the AI in the codebase technique applies directly: ask which outbound calls the service actually makes, and compare with the drawn edges. The discovered calls nobody drew are usually the interesting ones, and they are frequently a fraud check, an audit write, or a feature flag service that no requirement mentions.

Diagram against production. The strongest evidence available. Pull a correlated trace for one transaction from Datadog, extract the actual span sequence, and compare it to the drawn flow. The MCP and Datadog setup makes this a single question. A drawn flow and a real trace disagreeing is not ambiguity; it is a fact about your system.

BPMN: the four mechanical checks

Process diagrams have a grammar, which means they can be checked rather than merely reviewed. BPMN 2.0 files are XML, so a model reads them natively with no image step at all.

Read the attached BPMN 2.0 XML and report violations of these four rules.
Quote the element id for each.

1. GATEWAY COMPLETENESS: every exclusive gateway must have an outgoing
   sequence flow for every possible value of its condition, including a
   default flow for the unexpected case. Report gateways without a default.
2. ERROR BOUNDARY: every service task or send task that calls an external
   system must have a boundary error event or a compensating path.
   Report tasks without one.
3. TERMINATION: every path must reach an end event. Report any element
   with no outgoing flow that is not an end event.
4. WAIT BOUNDS: every intermediate catch message event and every receive
   task must have a boundary timer event. Report any that can wait forever.

Then list every human task with no stated SLA and no escalation path.

Rule three catches the single most common BPMN defect: a path that simply stops. In a modeller it looks fine, because a dangling element is visually indistinguishable from a tidy end. In a process engine it is an instance that sits in the database forever, and six months later someone asks why there are eleven thousand stuck processes.

Rule four is the one that matters to the business. A process waiting for a message with no timer waits indefinitely. Ask the business what should happen after two hours of no response and you will get a real answer, which becomes a real requirement. Nobody asks, because the diagram looked complete. The broader modelling practice is in BPMN with AI.

From gaps to requirements, in the pipeline format

The output of this stage is not a report. It is rows in requirements/gaps.yaml, which feeds the blind spot review and eventually the test conditions.

# requirements/gaps.yaml
- id: GAP-017
  source: diagram
  artifact: artifacts/payments-architecture-v3.png
  evidence: >
    Edge "Processor -> Sanctions" drawn as a solid synchronous arrow
    with no label, no timeout note, and no alternate path.
  question: >
    What happens to a payment when the sanctions service is unavailable
    or does not respond within the timeout? Hold, reject, or accept and
    screen later?
  lens: failure-path
  severity: high
  asked_of: Head of Financial Crime
  status: open              # open | answered | accepted-risk
  becomes: null             # REQ id once answered

- id: GAP-018
  source: diagram-vs-contract
  artifact: artifacts/payments-architecture-v3.png
  evidence: >
    Diagram shows "Processor -> Channel: settlement confirmation" as a
    direct arrow. openapi.yaml has no such callback; events.md publishes
    `payment.settled` to Kafka topic np.payments.settled.
  question: >
    Is the customer notification synchronous or event driven? REQ-009
    promises confirmation "immediately", which an event flow cannot
    guarantee.
  lens: sync-vs-async
  severity: high
  asked_of: Solution Architect
  status: open
  becomes: null

The becomes field is what closes the loop. A gap is not done when somebody answers it in a meeting; it is done when the answer exists as a requirement with an id. Add a validator rule that an answered gap must have a becomes value, and gap closure becomes as mechanical as coverage.

What AI gets wrong when reading diagrams

Know these before you trust the output.

• Hand-drawn and whiteboard photographs. Accuracy falls off sharply. Transcribe those yourself and use the model on the transcription.
• Layout implying meaning. If your team’s convention is that left to right means time and top to bottom means criticality, the model does not know that unless you say so. Put the convention in the prompt.
• Overlapping and crossing lines. In a dense diagram a model will occasionally attach an arrow to the wrong box. Always verify the edges that matter most by eye.
• Colour as semantics. Red for synchronous and blue for asynchronous is common and invisible to a model that was not told. Include the legend explicitly.
• Confident completion. Asked “what does this diagram show”, a model produces a fluent, complete-sounding description including things that are not drawn. This is precisely why the transcription step forbids interpretation and why NOT SPECIFIED must be an allowed answer.

The general point: a model reading a diagram is doing transcription and interrogation well, and inference badly. Keep it on the first two.

The takeaway

The diagram you were handed is a picture of the happy path drawn by somebody who has since moved teams. Extract it to structured text so it can be checked, interrogate every arrow with the five failure questions and every box with the four ownership questions, and diff the result against the API contract, the code, and a real production trace. Then write the gaps into a file with ids, owners, and a field that records which requirement each one became.

Do this on a diagram you are already working from today and it will produce questions your next workshop cannot ignore. The systematic version of the same instinct, applied to the whole requirement set rather than one diagram, is the blind spot review. For the wider systems analysis toolkit, see The Technical Skills Guide for BAs, or browse everything at The Tech BA Toolkit.

Ahmed is a Senior Technical Business Analyst with 10+ years in banking and payments. He builds practical guides and tools for analysts at The Tech BA Toolkit.

Tags: Systems Analysis, AI, Diagrams, BPMN, Requirements