Diagram Provenance

Every diagram is a claim about a system at a moment. Undated, it reads as a claim about the present, which is how a reviewer ends up asking the question every architecture team dreads: how do you know this is still true?

Provenance is the cheapest possible answer. Three facts in the corner of the image — source, date, next refresh — change how the diagram is read, from an assertion to a dated observation. The paradox teams report is that adding them increases trust rather than reducing it, because a reader who knows the age can calibrate, while a reader who does not will either over-trust or dismiss the whole document.

Why it matters

Compliance packs, onboarding material and incident runbooks all contain diagrams that were true once. The failure is not that they are old; it is that nothing on the page distinguishes an artefact refreshed last week from one signed off eight months ago. In a regulated review, a point-in-time attestation with no drift detection is a weak control; the same diagram with generation source and a scheduled diff is a strong one.

Implementation patterns

• Generate what can be generated. The inventory of data stores from infrastructure definitions and the catalogue; the flows from warehouse lineage metadata; egress crossings from network policy and outbound allowlists.
• Review the diff, not the picture. Run the generation on a schedule and make the change set the quarterly review artefact. Humans reviewing a diagram they have seen before see nothing.
• Keep the judgement by hand. Trust boundaries, legal purpose labels, and which flows are permitted. No tool knows that the fraud model and the marketing warehouse are different purposes under different contracts, and that judgement is the actual content of a compliance pack.
• Keep a deliberately simplified human view alongside the generated one. A picture of every table is accurate and unreviewable, which is a different failure from being stale.
• Put the provenance in the image, not in the page around it, because diagrams are pasted into chat, decks and tickets, and the surrounding context is lost immediately.

Industry example

The practice is standard in data engineering, where column-level lineage from orchestration and warehouse tooling has made generated flow documentation routine since the late 2010s. Teams maintaining privacy records under GDPR-era obligations, in force since 2018, have converged on the same split: automated discovery of stores and flows, human classification of purpose and lawful basis, and a scheduled comparison between the two.

Failure scenarios

• The confidently wrong diagram, trusted because it is polished and signed, describing a system that changed in March.
• The unreviewable generated diagram, containing every table and read by nobody.
• Drift that nobody detects, where an analyst's derived table holds personal data that appears on no map.
• A refresh that quietly stops, because the generation job failed and the diagram simply kept its old date, which is why the next-refresh date matters as much as the last one.

Trade-offs

Generation costs a pipeline to build and maintain, plus the discipline of a scheduled review. Hand-drawn diagrams cost nothing up front and decay invisibly. The exchange is worth making when the estate is larger than one person can hold, or when the people changing it never see the documentation. Below that, a dated hand-drawn diagram with a calendar reminder is proportionate and honest, and claiming otherwise is how documentation programmes lose credibility.

When not to use it

Do not build lineage tooling to document three services and one database. The provenance line still applies — it costs one sentence — but the generation machinery does not. The rule worth following: always date a diagram, generate one only when the number of things it describes exceeds what a person can verify in an afternoon.

Interview question

Q: An auditor asks how you know your data-flow diagram is current. It was signed off eight months ago and is accurate as far as you know. What do you tell them, and what do you propose?

What a strong answer covers: not defending the artefact, but naming the control gap: a point-in-time attestation with no drift detection · proposing continuous discovery of stores and flows with a scheduled diff, and a quarterly human review of differences · keeping trust boundaries and purpose labels as human judgement · adding provenance to every diagram so its age is visible · and the honest framing that auditors generally prefer evidence-producing controls, so this is a stronger position than the current one rather than an admission.

Quick check

Quiz: What does a provenance line change for the reader? It converts an implicit claim about the present into a dated observation they can weigh, which is the difference between over-trusting and calibrating.

Flashcard: Which part of a data-flow diagram should never be generated? — Trust boundaries and purpose labels, because they are legal and organisational judgements no tool can infer.