How to cover all the important aspects of an architecture?
How often have you finished an architecture artifact and then realized you forgot to cover one key aspect? That leads to rework, and it hurts. And the cost of rework for an architect is really high.
I solve this by working top-down. I build a kind of outline for the artifact.
What aspects are worth covering, on average?
🔹 Critical decisions.
Usually there are at most three, and they form the foundation of the solution.
🔹 Whiteboard.
A high-level description of the solution as a component or process diagram.
🔹 External interfaces.
How the system being changed interacts with external systems. This includes a diagram, integration protocols, and an ADR.
🔹 Internal interfaces.
How components, or steps in a process, interact with each other. This includes a diagram, integration protocols, and an ADR.
🔹 Data model.
An ER diagram with crow’s foot notation that covers only the most important fields (I skip things like id and timestamps), because someone else can fill in the rest.
Read and write use cases with actors (who queries what, and who writes what).
And of course, an ADR.
🔹 Topics.
This is the business domain broken down into subdomains.
How do you identify those subdomains?
Remember how we defined the system’s Inputs and Outputs?
Now we define Core Functions. These are actions (verbs) that describe how an Input becomes an Output.
For example: “Build an employee profile” for the Input “Employee data” and the Output “Employee profile” from the previous post.
Those Core Functions are our topics.
⚡️So in the end, we get a solution skeleton that makes it hard to miss important decisions.
Here are some examples of finished architecture specs that follow this outline.
How do you make sure you don’t miss key aspects of a solution?


