Multi-account AWS architecture diagrams: the org view and the workload view

The org view answers what accounts exist and why. Draw the root, then organizational units, then accounts inside them. The structure most landing zones converge on is recognisable: a management account on its own, a Security OU holding the log archive and audit accounts, an Infrastructure OU holding the network and shared services accounts, a Workloads OU split into production and non-production, and a Sandbox OU for experiments.

What makes this view useful rather than decorative is the annotations: which service control policies apply at which OU, which accounts are created by the landing zone automation, and which are legacy accounts invited into the organization later. Those two categories behave differently under audit, and the diagram is the only place people look for that distinction.

The workload view keeps the shape of a normal architecture diagram, with account boundaries as the outermost containers. Only the accounts the workload touches appear. A checkout system might span three: the network account holding the Transit Gateway, the workload account running ECS and Aurora, and the security account receiving logs.

Cross-account edges are where this view earns its keep. Draw the Transit Gateway attachment from each spoke VPC to the hub, PrivateLink endpoint services where one account exposes an API to another, VPC peering only where it genuinely exists, and cross-account assume-role paths where an account reads data in another. Centralised log delivery to the log archive account is worth one arrow, because it is the path an auditor will ask about first.

The case that consistently confuses readers is Resource Access Manager sharing: a workload account running instances inside subnets owned by the network account. Draw the subnet in the owning account and the instance in the consuming account, with the share stated on the boundary, or the diagram implies an ownership that does not exist.

In code, an account boundary is usually a provider alias with an assume-role block, and the differences between environments live in tfvars. That means the account topology is already written down, and reading it from source is more reliable than asking three people which account holds the Transit Gateway.

Datadef parses every .tf and .tfvars file in a connected repository, resolves variables to their values where they are declared, and keeps per-environment counts on a single node rather than emitting one diagram per environment. Nothing runs against your accounts: no terraform init, no state file, no AWS credentials.

Stack detection needs no configuration. A directory of .tf files that no module call anywhere in the repository names as its source is a root module, so the per-account and per-environment directories a landing zone is usually laid out in each become their own stack, and each stack becomes its own zone on the canvas. Environment names come from the tfvars layout, matched anywhere in the path, so infra/network/environments/prod/main.tfvars registers prod without anyone declaring it. The generated module reference table then carries a Stack column, which is where a reader checks which account a module was applied into.

provider "aws" {
  alias  = "network"
  region = "eu-west-1"
  assume_role {
    role_arn = "arn:aws:iam::111111111111:role/TerraformExecution"
  }
}

provider "aws" {
  alias  = "workload_prod"
  region = "eu-west-1"
  assume_role {
    role_arn = "arn:aws:iam::222222222222:role/TerraformExecution"
  }
}

The test is not whether the picture looks complete. It is whether somebody who was not in the room can answer four questions from it without asking anyone. Each one corresponds to a mistake the two views above exist to prevent.

Which account owns a resource, and where that differs from which account uses it. This is the Resource Access Manager case: subnets owned by the network account, instances launched into them by a workload account. A diagram that cannot express the difference is asserting an ownership that does not exist.

What the path between two accounts is, and what carries it. A Transit Gateway attachment, a PrivateLink endpoint service, a VPC peering connection, and a cross-account assume-role are four mechanisms with four different failure modes, and an unlabelled arrow between two account boxes names none of them.

Where logs and security findings land, and by which mechanism. It is the first thing an auditor asks and usually one arrow to one account the workload team never thinks about. And finally, which accounts the landing zone automation created and which were invited into the organization afterwards, because those two behave differently under service control policies and under audit.

| Question | Where the diagram answers it |
| --- | --- |
| Who owns this subnet | The account container it is drawn in |
| Who launches into it | The account container the instance is drawn in |
| How do these accounts talk | The label on the cross-account edge |
| Where do logs land | One arrow into the log archive account |
| Created or invited | An annotation on the account node |

• AWS VPC diagram: subnets, AZs, and routes
• Multi-region AWS architecture diagrams
• AWS Terraform diagram generator
• Terraform module diagram
• Repo to diagram: repository sync