How to make an architecture diagram on the whiteboard
- 1Start from the architecture template, which loads on this page with a client, API, service and database.
- 2Rename the boxes to match your own components and add any that are missing.
- 3Draw arrows for each request or data flow and label them with the protocol, such as HTTPS or gRPC.
- 4Draw boundary boxes around groups such as a VPC, a cluster or a third-party service.
- 5Add a title and a small legend, then export SVG for docs or PNG for chat.
Pick one level of detail per diagram
The C4 model is a widely used way to structure architecture diagrams at four zoom levels: System Context (your system, its users and the external systems it talks to), Containers (apps, services and databases), Components (the main parts inside one container) and Code.
Most teams only need the first two or three. Mixing levels, such as showing classes next to whole services, is the most common reason architecture diagrams become confusing.
Conventions that make diagrams readable
Label every box with its name and technology, for example 'Orders API (Node.js)', and label every arrow with what flows and how, for example 'POST /orders (HTTPS)'. Point arrows in the direction of the request or the data.
Use one shape per kind of element, such as rectangles for services and a distinct shape for databases, and draw dashed boundary boxes for trust zones, networks or ownership. Add a title, a date and a small legend so the diagram still makes sense months later.