Architecture in Plain English
Architecture decisions are usually explained in jargon, which hides the trade-off that actually matters. This eight-part series explains common decisions in plain language: what an API gateway does and does not do, when a module should become a service, why a successful payment can still end in a failed order, which question logs, metrics and traces each answer, and how status codes should change what a caller does next. The last three parts turn to the documents that describe systems: diagrams that carry evidence, reviews built on deltas, and documentation that stays alive. One fictional South African online retailer carries the examples, and every figure is illustrative.
8 articles
- Part 1What an API gateway actually does, and when you need oneAn API gateway is often described as 'another hop in front of your services'. That undersells it and oversells it at the same time. Part 1 of Architecture in Plain English explains the five jobs a gateway does, what it does not do, and how to tell whether you need one yet.8 min read
- Part 2When a module should become a microserviceSplitting a module out of an application turns a function call into a network call and a shared table into somebody else's data. Part 2 sets out five tests to apply first, and the order in which to extract when the answer is yes.6 min read
- Part 3Why a successful payment can still end in a failed orderThe customer's card was charged, but the order failed. This is not a rare bug: it is what happens when one business action spans several systems with no shared transaction. Part 3 explains sagas, compensation and idempotency in plain English.6 min read
- Part 4Logs, metrics and traces: what each one tells you when production breaksMost teams collect all three observability signals and still struggle during an incident, because nobody agreed which question each one answers. Part 4 follows one checkout incident through metrics, traces and logs, and shows what to put in place before the next one.6 min read
- Part 5HTTP status codes as operational signalsA status code is an instruction to the caller: fix your request, slow down, try again later, or do not try again at all. Part 5 explains which responses are retryable, how to handle rate limits, and why every failure needs a correlation ID.6 min read
- Part 6Architecture diagrams should be evidence, not artworkAI can now draw a convincing architecture diagram in seconds, which makes convincing fiction cheaper than ever. Part 6 explains what turns a diagram into evidence: a typed source model, marked levels of support, pinned revisions and validation that knows its own limits.6 min read
- Part 7What changed in the architecture? Show me the deltaArchitecture reviews often ask people to compare two pictures and spot the difference. Part 7 explains why a delta view, listing what was added, removed and changed, makes reviews faster and sharper, and what each kind of change should be asked.6 min read
- Part 8Living architecture documentation without pretending it is automaticTools can now derive diagrams from code on every merge, which tempts teams to declare architecture documentation solved. Part 8 separates what a repository can tell you from what only people can supply, and sets out two rhythms that keep documentation alive.6 min read
Working through any of this in your own organisation?
These articles come out of delivery work rather than theory. If the problems in this series look familiar, a short scoping conversation is usually the quickest way to work out what is worth doing first.
Talk to CloudNala