I used to be the person who drew the diagrams.

You know the one. New engineer joins, asks "how does the system fit together?", and everyone turns to look at me. So I'd open Lucidchart, spend an hour rebuilding the picture from memory, drop it in Notion, and feel briefly like a responsible adult. Two months later that same picture would be quietly, confidently wrong, and I'd draw it again.

This is the story of how I stopped doing that.

The diagram graveyard

At one point I counted. Across our wiki, our repos, and three different whiteboarding tools, we had eleven architecture diagrams. Not one of them agreed with another. Not one of them matched production.

The diagram graveyard: a pile of pictures nobody trusts, versus one map that does.

There was the "official" one in Confluence, last edited eight months ago. There was a FigJam board from an offsite that had four services we'd since deleted. There was a Mermaid block in a README that was almost right, which is the most dangerous kind of wrong. And there was a photo of a whiteboard in someone's Slack DMs that, honestly, was probably the most accurate of the lot.

The diagrams weren't the problem. The format was. Every one of them was a picture, a thing a human had to remember to update, by hand, forever. Nobody's OKRs said "keep the architecture diagram in sync." So nobody did. And I couldn't blame them, because I didn't either.

The moment it clicked

The click came during an incident.

Payments were failing. We were nine people on a call at 1am trying to reconstruct, from memory, what actually talked to the payment provider. Someone pulled up the Confluence diagram. It showed a service that had been decommissioned in Q1. We lost twenty minutes chasing a ghost.

When it was over, I wasn't angry about the outage. I was angry that we had eleven diagrams and not one of them could answer a simple question: what depends on this thing?

That's when it hit me. I didn't need a better drawing. I needed the architecture to be something I could query. A picture can't answer "what's downstream of payments." A data structure can, instantly.

What I do now

These days I don't draw architecture. I model it. The rules I settled on are boring and that's the point:

• One source of truth, and it's structured. The architecture is a data file (nodes, edges, metadata) that lives in version control. Not a picture. A model.
• The picture is generated, never hand-maintained. If I want a visual, it renders from the data. When the data changes, the picture changes. There is no separate thing to forget.
• Operational facts ride on the map. Each service carries what it costs, who owns it, and what environment it's in. The map isn't just topology; it's the thing I actually reach for during an incident or a cost review.
• The machines get a copy. Our AI coding agents read an exported version of the map. They stopped guessing at our architecture, which made them dramatically more useful.

The eleven diagrams collapsed into one living map. And for the first time, the answer to "is this still true?" was just yes.

The part where I admit I built a product about this

I'll be honest about the arc here, because this is a personal blog and you can smell a pitch coming a mile off.

I got obsessed with this problem, and obsession is how products get made. My team at 8StarLabs ended up building Canopy, an architecture canvas where every map is structured data you own, not a drawing. You point it at a repo (or a template, or a canopy.json), it maps your services, you attach spend and ownership, and then (the part I care about most) you can export a CLAUDE.md / AGENTS.md for your agents or serve the whole thing over MCP.

It's the tool I wish I'd had on that 1am call. But whether or not you ever use it, take the lesson for free: the diagram is not the asset. The data is.

If you're standing in a diagram graveyard right now

Here's the smallest possible first step, no tooling required:

1. Pick your most-referenced diagram. The one people actually open.
2. Ask it a question you'd ask during an incident ("what depends on X?") and notice that it can't answer.
3. Write the same architecture down as structured text instead: a list of services and what they connect to. Commit it.

That's it. You've just moved one rung up, from a picture nobody trusts to data you can build on. Everything else, including whether you ever adopt a dedicated tool, follows from that one move.

I drew my last architecture diagram a while ago now. I don't miss it. The system finally has a map that tells the truth, and I got my 1am back.

Kei Lok is Lead Engineer at 8StarLabs, where the team builds Canopy and 8StarLabs UI. Say hi on X.