How to explain infrastructure to a new joiner: three questions, one picture, no repo tour

They can read HCL. Most engineers can read a resource block on their first day, and the ones who cannot will manage by the second. What the repository does not tell them is which of the directories is load-bearing, which environment reflects production reality, which resources exist but are not managed here, and who to ask when something is on fire.

It also does not tell them proportion. The Azure platform repository this parser was built against declares 123 resources and curates to roughly 36 drawn nodes; the remainder is role assignments, grants, key vault secrets, and network interfaces, counted in a note instead of drawn. A newcomer reading file by file has no way to know which resources carry the architecture, so they weight all 123 equally and remember none of them.

Question one, what does this build. Answer it with one diagram and a five-minute narration. Not a tour of files: a picture with the real component names on it, so that when they later read a directory called lakebase they can place it.

Question two, where does the data or the request go. Trace one concrete path out loud, end to end, including the boring hops. This is the part that turns a static picture into a mental model, and it is the part that never survives in written docs.

Question three, what happens when I change something. Branch, plan, who reviews, which stacks apply in which order, what is protected. Ten minutes here prevents the week-three incident where someone applies the wrong stack because nobody said the stacks have an order.

Then stop. Anything more is reference material, and reference material should be read, not narrated. Point them at the module reference table and let them go.

00:00  what this builds        one diagram, real names, five minutes
00:05  the walkthrough         trace one request or one dataset, end to end
00:35  the change procedure    branch, plan, review, apply order, protections
00:45  what we do NOT own      unmanaged resources, other teams, legacy
00:55  first task              a scoped change in the least dangerous stack
01:30  end

A current architecture diagram, an environment map, and a list of what the repo does not own. That is the whole pack. The reason to generate the diagram rather than draw it is specific to onboarding: a new joiner cannot detect that a diagram is wrong. An experienced engineer sees a missing queue and corrects for it silently; a newcomer builds their entire mental model on the error and carries it for months.

Connect the repository read-only, pick the branch that represents reality, and the diagram regenerates on a daily sync. Node identities derive from Terraform addresses, so a re-sync updates the picture rather than reshuffling it, and the diagram someone narrated last quarter still looks like the one on screen today. A node you dragged more than twelve pixels from where the previous sync left it counts as hand placed and is put back there after each redraw, so an arrangement made for a session survives the next commit.

Put it where onboarding actually happens. A live embed renders the current diagram in a Notion or Confluence onboarding page with no account required to view, which matters on day one when the new joiner's access requests are still pending. Keeping the surrounding text current is its own habit, covered in onboarding docs upkeep.

• Keep onboarding docs up to date
• Tribal knowledge in engineering teams
• Visualize a Terraform repository
• Repo to diagram: repository sync