Which Walls Are Load-Bearing? What I've Learned About Architecture Docs

If you've ever renovated an old house, you'll know the moment.

You want to knock through between the kitchen and the back room. The builder taps the wall, frowns, and asks: "Do you know if that's load-bearing?"

Nobody knows. You might even have the original plans. They show the wall clearly enough. What they don't tell you is why it's there, what it's holding up, or what the person who built it was worried about.

I've watched engineering teams hit that exact moment more times than I can count. So if you're about to write your first Technical Architecture Document, or your fiftieth, here's what I'd tell you over a coffee.

Plans tell you what. You need to know why.

Most architecture docs I've read are plans. They show the boxes, the arrows, the services and the data stores. They're often beautifully drawn.

But the code already tells you what was built. What nothing else tells you is why it was built that way, what else was on the table, and what the team knowingly gave up.

That's the part that matters when someone comes back in three years with a hammer. And in platform work, someone always comes back with a hammer.

Platform decisions are the foundations and the plumbing. Other teams build their rooms on top of them, usually without ever seeing what's underneath. Get a foundation wrong and you don't just have one problem. You have a problem in every room in the house.

The fork you'll meet more than once

Sooner or later in platform work, you'll stand at the same fork I've stood at many times. Do you build upwards on the house you've got, or pour new foundations alongside it?

Building upwards is the natural pull. The house is standing, everyone knows their way around it, and a new floor goes up quickly. Building new is slower to start, and for a while you're paying to run two houses at once.

But every floor you add sits on the original foundations, and foundations are rated for a load. The house was built for two floors, which was exactly right at the time. Add a third and they strain. Add a fourth and the cracks appear. Keep stacking and you get subsidence: problems in every room that nobody can trace to a single change.

The plot matters too. The classic example in our world is a platform locked to a single region. It works perfectly well until the day you need it to move, and then you find out you can't pick up a house and set it down somewhere else. That's a big part of why I've come to favour regionless, location-agnostic platform design.

Neither answer is always right. That's exactly why this decision deserves a proper doc.

The bit nobody puts in the doc: people

Here's something I wish someone had told me earlier. Architecture decisions are rarely made on the arguments alone.

The people who built the original house usually love it, and they should. It's years of their work, and it got the business to where it is. When you propose new foundations, it can easily sound like you're telling them their house was built wrong. It wasn't. It was built for a different time.

If you've ever watched someone defend a car they restored themselves, you'll recognise the feeling. We all do it. Give it a few years and you'll be defending your own house too.

So when you write a TAD that proposes change, write it for the people in the room, including the ones who built what you're proposing to change. Say plainly what the existing system got right and why it made sense at the time. People find it much easier to move on from something when you've honoured it first.

And accept that a good doc won't win every argument. What it does is change what the argument is about. Once the trade-offs are written down, nobody can later say they were invisible.

What I look for when I review your doc

When you hand me a TAD, I'm really asking a handful of questions.

What problem are you solving, and for whom? If you can't tell me in a paragraph, you're not ready to design yet. Platforms built without a clear customer end up like a show home: lovely to walk through, and nobody lives in it.

What are you stuck with? Budget, compliance, existing contracts, the skills on the team, the cloud provider's real limits. Constraints are the planning permission. They explain choices that otherwise look strange.

What else did you consider? This is the bit I care about most, and it's almost always the thinnest. Think of your sat nav. It shows you three routes: the motorway, the back roads, and the toll road. A good decision record keeps all three on the screen, with the times and costs, and explains why you took the one you did. Always include "do nothing" as one of them.

What are you giving up? Every architecture is a bet. I want one honest sentence: "We chose this, and we accept that." If that sentence makes you uncomfortable, good. That's the sentence that will save someone later.

Who has to change, and how hard is it for them? In platform work, your customers are other engineers. If your decision means fifty teams have to re-plumb their kitchens, that belongs in the doc.

What happens when it breaks, and what will it cost at ten times the size? Resilience, recovery, blast radius, the bill at scale, and who gets the phone call at 2am. Houses rarely fall down on a sunny day. They fall down in the storm you didn't plan for.

What don't you know yet? If there are no open questions, you're either building a garden shed or you're not being straight with me.

Walking the fork as a decision record

Take that build-up-or-rebuild fork. Written as a decision record, the heart of it fits on one page.

Option A: build upwards on the existing platform. Faster start, familiar ground, lower upfront risk. Every new floor loads the old foundations, including any region lock and scaling limits.

Option B: build new, location-agnostic foundations in parallel. Slower start, more investment, and a period of running two estates. The payoff is a platform you can move, recover and grow without hitting the old walls.

Option C: do nothing. Keep patching. Cheapest today, and the cracks get wider every year.

Either A or B can be the right call, depending on your timeline, money and appetite for risk. The doc's job isn't to pick for you. It's to make the choice honest.

So here's the habit I'd urge on you. Don't stop at presenting the options. Ask whoever makes the call to put their name to one sentence: "We choose A. We accept region lock-in and these limits in exchange for speed, and we'll revisit if X happens."

People think harder about a trade-off when they have to sign it. And if the decision goes against you, that sentence is your best friend later. It turns "I told you so", which never helps anyone, into "we agreed to revisit at X, and X has happened."

A trade-off nobody signed isn't a decision. It's a surprise waiting to happen.

What you can leave out

Twelve diagrams, pages of copied-in security boilerplate, every table name and resource ID. That's the estate agent's brochure: lots of nice photos, and not a word about the damp. The detail belongs in the code, where it stays true. My rule of thumb: if nobody could disagree with a section, it probably doesn't need to be there.

When you need one, and when you don't

You don't call a structural engineer to hang a picture. You do call one before you take out a wall.

Write a TAD when the change is hard to undo, when other teams will inherit it, when it's going to cost real money, or when good engineers genuinely disagree about it. For everything else, a decent PR description or a short Architecture Decision Record will do the job.

Keep the plans current

Give the doc an owner — a person, not a team. When the design changes, update it. When it's replaced, don't throw the old plans away. Pin the new ones on top and note what changed. The rejected history is often the bit that stops the next team knocking down the wrong wall.

The coffee test

Before you send your TAD round for review, try this. Could you explain the problem, the options, your choice and the trade-off you're accepting to me over a coffee, in the time it takes to drink it?

If not, that's fine. You're still designing. Call it a draft and invite the argument.

If you can, write that down first. That page is worth more than everything else in the doc.

A doc can't make the decision for you, and it won't talk anyone out of loving the house they built. What it can do is make sure that, whichever way the call goes, everyone knows which walls are load-bearing, and who agreed to build on them.