Diagram Desk

Software architecture diagram

Users, applications, and data stores, labeled in plain words.

High / highLow / highHigh / lowLow / low
Four cells from two axes. Label the axes before you fill names.

Context first, containers second

A software architecture diagram, system architecture diagram, or architectural diagram is a picture of how a system is divided. The useful first picture is a context diagram: the system as one box, the people who use it, and the other systems it talks to. The second picture splits the box into containers you could deploy or point at: a web app, an API, a database. Simon Brown's C4 model is one widely taught way to keep those levels separate. You do not have to adopt the whole method to refuse a single slide that mixes button labels with server names.

Arrows need verbs. 'Reads availability' is an arrow. A line with no words is decoration. This is not a data flow diagram in the strict sense, though the context picture is a cousin. It is also not a wireframe, which shows layout inside one screen.

Example: a club sign-up

Context: students and a coordinator use the club sign-up system. The system sends a mail through the school mail provider. Containers: a web app the student opens, a small API, and a database of sign-ups. Arrow: the web app submits a form to the API. Arrow: the API writes a row and asks the mail provider to send a confirmation. Stop there. Adding the brand of the database or the color of the button does not help this diagram.

Steps

  1. Draw one box for the system. Name it as a user would. Put people outside the box.
  2. Add only the outside systems you call. Mail, payments, a directory. Skip systems you merely admire.
  3. Split into deployable pieces. Web, API, database, or the equivalents you actually run.
  4. Label arrows with a verb. If you cannot name the data or the call, remove the arrow.

Questions

What is a system architecture diagram?
A labeled picture of a software system's parts and how they communicate. Start with the system as one box and the people around it, then split into applications and data stores.
How detailed should an architectural diagram be?
Detailed enough for the decision in the room. A context diagram settles scope. A container diagram settles what you will run. Class diagrams and screen layouts are different pages.
What should an arrow say?
A verb and a noun: 'writes a sign-up row' or 'sends confirmation mail'. An unlabeled line does not document an architecture.

Keep reading