Breaking Down a Complex System
Start from boundaries and inputs/outputs, not from the details
Help me break down [system name], for example [specific example]. Go in order: 1) draw the boundary first — what's inside, what's outside; 2) list the inputs, the outputs, and the goal it maintains; 3) break it into 3–6 subsystems, stating each one's responsibility and how they interface; 4) point out where the bottleneck or single point of failure is; 5) walk one concrete scenario through the flow and mark the steps I'd tend to overlook. Where information is missing, say it's uncertain — don't make it up.
How to use
Break down a system you already know first, then the new one — the sense of structure comes faster.
Good for
- You have inherited a system someone else built and need a mental model within two hours to start debugging
- The system got slow or a new requirement arrived, and you cannot say which parts a change will pull on
Not for
- It is an internal company system the model has no reliable information about, so it will confidently invent components and names
- The system is small enough to read in ten minutes, or you need one exact config value
Example
Input
System: a Kafka cluster, following one main path from producer write to consumer read.
What you get
The boundary should be Kafka owning persistence and replication but not business semantics. Five subsystems: network layer, log storage, controller, replica fetchers, group coordinator, each with its interface. The bottleneck is usually per-partition sequential append plus ISR sync, and the single point of failure in the old architecture is the controller (the ZooKeeper dependency). Walking a scenario should surface easily missed links such as the latency of acks=all being set by the slowest in-sync replica.
Common mistakes
- Starting with details (how the rebalance protocol works) before boundary and inputs, so the details have nowhere to attach and stay scattered
- Presenting its output as the real architecture: some components may be filled in from common designs and do not exist in your system
Try tweaking it like this
- Reverse the order: walk one concrete scenario first, then have it infer which subsystems are required, which surfaces missing pieces
- Add 'if traffic grows tenfold, which link breaks first and why', turning a static teardown into a capacity argument