The audit pack: the written description and the diagram have to agree

A system description in prose, covering what the service does and what it is built from. A data flow diagram showing where regulated data enters, where it comes to rest, where it leaves, and to whom. A view of environment separation, because the question of whether production data can reach a development environment is asked in some form in nearly every review. And an inventory of third parties that touch the data, with what each one receives.

Then the cross-check. The reviewer takes the diagram and samples controls against it: access records, key custody, backup and restore evidence, monitoring coverage. Every named component in the diagram is a place a question can be asked, and every unnamed one that appears in a log is a finding.

The failure mode is asymmetric in a useful way. A diagram that omits something is a gap you can close during the review. A diagram that shows something no longer true is a credibility problem that colours the rest of the pack.

The reader is not on your team and will not reconstruct implied structure. That imposes four concrete requirements. Boundaries drawn as named zones, so the account, network, or environment separation is visible rather than assumed. Edges labelled with what moves and in which direction, so a line is not open to interpretation. External providers named individually rather than grouped into a box labelled third parties. And datastores marked clearly, since they are where the sampling starts.

A Datadef canvas carries all four natively: zones for boundaries, labelled edges for flows, and real provider icons from a catalog of more than two thousand marks so a managed database reads as a managed database at a glance. The canvas exports as PNG or JPEG when the evidence pack needs a still image alongside the live version.

Resist the urge to draw everything. An audit diagram with every internal component is harder to defend than one that shows the data path clearly, because each drawn box invites a question and the ones that do not touch regulated data invite questions with no payoff.

A generated diagram takes that position by construction, and states what it left out. Identity wiring never becomes a box: role assignments, IAM policies, grants, permissions, secrets, and diagnostic settings are classified as wiring and counted in a note instead, in the form 27 wiring resources not worth boxes, 14 role assignments, 8 grants, 5 secrets. That shape suits a review twice over. The data path stays legible, and the count tells the reviewer how much access configuration exists to ask about, with the full inventory sitting in the generated module reference table rather than crowding the picture.

Most teams redraw the audit diagram at each cycle, because last time the artifact was a screenshot with no source anyone can find. That is a week of engineering time per cycle, spent reconstructing something the infrastructure code already states.

A diagram generated from the repository resets that. The picture is regenerated from the tracked branch, so the pack starts from a current view instead of from memory, and the prose description generated alongside it lists the same components. Two artifacts from one read cannot contradict each other, which removes one entire category of audit finding.

Environment separation gets the same treatment. For a Terraform repository the environments are read out of the tfvars layout rather than configured, so environments/DEV and environments/PROD are discovered and a resource created once per environment is drawn once with the real per-environment counts. The question of whether the two environments share anything becomes a reading of the diagram instead of a claim in the narrative.

Point-in-time evidence has an answer too. A repository connection can track a tag rather than a branch, so a diagram pinned to the release that was in production during the audit period sits alongside the one tracking main. One connection can back several diagrams, which is what makes holding both cheap.

Retention periods, encryption key custody, data processing terms with each vendor, incident notification commitments, and ownership of each control are not in the source code and will not be generated from it. Generating the map does not generate the controls, and any tool suggesting otherwise is selling something.

What it does change is where the effort goes. The mechanical part, an accurate current picture of what exists and a description that matches it, stops consuming the preparation window, and the judgment part gets the attention it needs. The same principle applies to security architecture documentation between audits, when nobody is watching and drift accumulates.

• Architecture diagrams for compliance audits
• Documentation audit checklist
• Keep security architecture docs current
• Generate architecture.md from a repository
• Diagram versioning