How to explain a system in a design review
· 7 min read
Being asked to explain a system in a design review is a strange kind of pressure. You probably know the system better than anyone in the room, and yet the explanation comes out in the wrong order: boxes before the problem, detail before the point, and then a question about a corner you wrote months ago that you can't quite picture.
None of that means you don't understand your own work. It means the explanation hasn't been shaped for listeners yet. This guide gives you a shape that works for most reviews, from a single new endpoint to a change that touches several services, with examples of what to say at each step.
Know what the review is for
A design review exists so that other people can find problems while they are still cheap to fix. Your job is to make the design easy to check, not to defend it. That changes how you prepare: instead of rehearsing why you're right, you work out what the reviewers need to see to decide whether you are.
Before you write a single slide or diagram, decide what you want from the room. It's usually one of three things:
- Approval to go ahead, because the design is settled and you want a last check.
- A choice between options, because you have two or three ways forward and need the team to pick one.
- Warnings, because you're early and want people to point at the parts most likely to hurt.
Say which one it is in your first minute. Reviewers listen differently when they know they're being asked to choose rather than to approve.
Start from the problem, not the boxes
Open with the problem in two or three sentences: what is broken or missing, who feels it, and the constraint that makes it hard. If people don't agree on the problem, nothing you say about the solution will land.
"So this is the webhook service, and it talks to the queue here, and then there's a worker, and the worker calls the partner API, and we've got Redis over here for the locks, and, um, the change is mostly in the worker…"
"When a partner's endpoint is down, we retry every webhook straight away and keep going until it comes back. Last week that meant one partner's outage filled the queue and delayed everyone else's events. I want to change how we retry so one bad endpoint can't hold up the rest. I'd like a decision between two ways of doing that."
The second version takes about twenty seconds, and by the end everyone knows the problem, why it matters and what you're asking for. The boxes can come next, and now they mean something.
How to explain a system: follow one request through it
The clearest way to explain a system is to follow one concrete thing through it from start to finish: a request, an event, a job, a user pressing a button. People understand a story with an order far better than a map of everything at once.
- Where it comes in. "A partner event arrives on the webhook endpoint and is written to the queue."
- What touches it, in order. "The worker picks it up, looks up the partner's endpoint and sends it."
- Where state lives. "The attempt count is stored on the message, not in the database."
- What comes back. "A 2xx marks it delivered. Anything else goes to the retry step."
- What happens when it fails. "After the last attempt it moves to the dead-letter queue and we alert the owning team."
Use the real names: the actual function, file, table or queue. "The retry policy in the worker" is easier to check than "the retry logic", and naming the file tells reviewers where to look if they want to read it afterwards.
Then take the failure path on purpose. Reviewers will ask about it anyway, and walking through it yourself shows you've thought about it. Timeouts, partial failures, duplicate deliveries and what happens during a deploy are the usual suspects.
Draw less, and label what moves
One diagram is usually enough. Draw only the parts your request passes through, label each box with its real name, and label each arrow with what travels along it: an event, a call, a row. An arrow without a label makes people guess.
Don't read the diagram out loud. Use it as the map while you tell the story of the request, pointing at each part as you reach it.
Name the trade-offs before someone else does
Every design gives something up. If you say what yours gives up, the conversation becomes about whether that cost is acceptable. If you don't, it becomes about whether you noticed it. A simple pattern helps: what you chose, what you chose it over, why, and what it costs.
"I've gone for exponential backoff with random jitter rather than a fixed delay, because a fixed delay makes every waiting event retry at the same moment. The cost is that a single event can now take up to about twenty minutes to be delivered after an outage, and support will need to know that."
Mention the option you rejected even if nobody asks. Someone has probably thought of it, and hearing why saves a long discussion.
Answering questions about your own code
The hardest moments are often questions about code you wrote some time ago, or code a coding agent helped you write, where you know roughly what it does but not the exact detail. Guessing is the mistake. A wrong number said confidently does more damage than a pause.
- Say what you know, and how sure you are. "I believe it's six attempts. Let me check rather than guess."
- Have the code open. Keep the files you're likely to be asked about in tabs, so checking takes seconds, not a screen share and a search.
- Offer to follow up. "I'm not sure how it behaves during a deploy. I'll find out and add it to the review notes today." Then do it.
You can also predict most questions. Before the review, write down the five things you'd ask if someone else were presenting: what happens when it fails, how large it gets, how we roll it back, how we'll know it's working, and who owns it at three in the morning. Have a one-sentence answer for each.
A short checklist for the day before
- Write the problem in three sentences and the decision you want in one.
- Pick the one request you'll follow through the system.
- Draw one diagram with real names and labelled arrows.
- Write down each trade-off and the option you rejected.
- List the five questions you'd ask, with an answer for each.
- Open the files you're most likely to be asked about.
- Say the whole walk-through out loud once, and time it.
The last step matters more than it looks. An explanation that feels clear in your head often has gaps you only hear when you say it: the step you skip because it's obvious to you, or the name you can't quite remember. Saying it once, alone, finds most of them.
We built Staging Mind for exactly that moment. It reads a digest of your repository, so when someone asks about your own code in a meeting you can press one key and get a few short pointers, each with its file and line. Before the meeting, you can practise the walk-through out loud and be asked the follow-ups.
Frequently asked questions
- How long should a design review presentation be?
- Leave at least half the time for questions. If the review is booked for an hour, aim to finish your walk-through in twenty to twenty-five minutes, because the questions are where the review does its job.
- What if I don't know the answer to a question?
- Say so, say what you'd check, and offer to follow up by a specific time. Reviewers trust a clear "I'll find out by this afternoon" far more than an answer that turns out to be wrong.
// Staging Mind
If explaining your own code under questions is the part you dread, Staging Mind gives you pointers from your repository with the file and line when you're asked, and a place to practise the walk-through first. No bot joins your call.
Start free: one session on us