willgarrett.iowillgarrett.io — ~/notes/001-read-the-deploy.md
~ ❯ cat notes/001-read-the-deploy.md

001-read-the-deploy.md

Read the deploy, not the diagram

Every environment has two architectures — the one on the wiki and the one that is running.

At the start of an engagement, I want to see what is running. Documentation gives me the team’s account of the system. The deployed environment gives me something to compare it with.

I start with an inventory: accounts, regions, load balancers, public endpoints. Then I follow a request through the parts that serve it. Where does the application get its configuration? Which database does it reach? What deploys this version, and who can change it? Those questions give the architecture diagram some weight.

The gap needs an explanation

A resource that does not appear on the diagram deserves a conversation. It might be abandoned. It might also support a customer workflow that nobody has had time to document. Removing it because it looks untidy would be an expensive way to find out.

This is where consulting requires some restraint. Arriving with fresh eyes makes inconsistencies easy to spot. Understanding why they exist takes longer. A manual deployment might be holding together a migration. An unusual permission might be the residue of an incident. I want to hear from the person who made the decision before I recommend undoing it.

The diagram is useful here. It shows how the team understands the system, including the boundaries they expect to exist. If production disagrees, we have a specific question to investigate together.

Turning an inventory into work

An inventory alone is a poor deliverable. A long list of surprises can leave a team with more anxiety and no better idea of what to do on Monday.

I want each meaningful discrepancy connected to a consequence. An unowned service needs an owner and a decision about its future. An undocumented dependency needs to appear in the recovery plan. A deployment that relies on someone’s laptop needs a reproducible path another engineer can use.

Some differences can wait. Others change the scope of the engagement. Before drawing a replacement architecture, I want us to agree on which problems are affecting the people operating this one. Then the diagram can become a record of decisions we have checked against the environment.