As part of our final project handoff to Tandem clients, we provide a diagram of the product’s architecture — a visual depiction of the various systems, platforms, and tools that work together to support a software product.
At Tandem, documentation is more than just a best practice: it’s a way we demonstrate our values. Thoughtful documentation (like a system architecture diagram) is a way to show empathy for other coders by helping them quickly acclimate to complex projects. A good diagram also helps our clients and their stakeholders fully understand how our work interacts with their other existing systems, and gives them the information they need to do further enhancements in the future.
Here’s how we create system architecture diagrams.
How to diagram system architecture for software products
Software products are often complex. But the diagramming process doesn’t have to be complicated!
- Start with a whiteboard. Write down every element of the system that you can think of, then use lines and arrows to show how they connect to each other. Here’s what one of our recent whiteboard sessions looked like:
- Pick a tool. If you are already confident with a design tool like InDesign or Figma, great! If not, we recommend a tool like Miro, which is easy to use for non-designers and has a robust icon library.
- Draft your diagram. Take your whiteboard diagram and recreate it in the design program. At this point, we recommend keeping it simple: this kind of diagram is meant to be a high-level overview of an entire system. Complexity and details can be added in later diagrams, but this draft is the first of many.
- Get feedback. After making your initial draft of the diagram, get feedback from your teammates: does the diagram make sense? Are you leaving out any important systems or relationships? On our latest system architecture diagram, our reviewers recommended we add dotted lines to show when we are using a tool to run several functionalities separately. Getting a fresh perspective always makes your work better.
- Make it look nice. This isn’t just about aesthetics: using color, iconography, and other design elements will help make your diagram easy to understand at a glance.
-
- Make sure your use of icons is consistent; if you’re using the same icon more than once, it should represent the same thing each time.
- Size your diagram to print on a standard 8.5” by 11” piece of paper. Some clients like to be able to review work on paper, plus it’s a nice printable for engineers to keep on their desk as a quick reference while working on the project.
After moving through these steps, that original whiteboarded draft will look something like this:
A complex system of databases, servers, and APIs could take hours to explain. But a clean, well-thought-out diagram makes the relationships easy to understand and remember.
Do you love well-documented software products? We do too. Let’s work together: shoot us a message!
