A software architecture diagram is a map of a system: the services, the data stores, the outside providers, and the connections between them. A good one lets a new engineer, or a curious product manager, understand the system in a minute.

Who the diagram is for

Decide the audience first. It changes everything:

  • For the whole company: a handful of boxes, such as web app, API, database, payments, email. No protocols or ports.
  • For engineers joining the team: each service, the main data stores, queues and external providers, with what flows between them.
  • For a design review: just the parts that are changing, in detail.

One diagram can't serve all three. It's fine to have a simple overview that links to detailed ones.

What to include

  • Services and apps: what your team runs.
  • Data stores: databases, caches, buckets.
  • Messaging: queues and event streams.
  • External services: payment, email, sign-in and AI providers.
  • Connections: arrows labelled with what flows, such as "REST", "Orders" or "Events".

What to leave out

  • every server and container, unless the diagram is about deployment
  • connections nobody needs to reason about, like logging, on an overview
  • abbreviations only one team understands

How to draw an architecture diagram

1. Start from the user

Put whatever people use, like the web app or mobile app, on the left or top.

2. Add services in the order requests reach them

Follow a request through the system: app, API, workers, databases.

3. Label every arrow

"API -> Database" says little. "API -> Database: Orders" says what moves.

Put related services into a named group, such as "Billing" or "Data", so the big picture shows at a glance.

5. Use recognisable icons, sparingly

Icons help people spot a database or a queue instantly. Don't let them crowd out the labels.

An example you can type

In a Nodeslate architecture diagram, type a service for a box, or A -> B: label to connect two:

Web -> API: REST
API -> db: Orders
API -> Queue: Events
Worker -> Queue: Reads

Put related boxes in a named group with group: Billing: Payments, Invoices. Nodeslate picks a fitting icon as you type, including the official AWS architecture icons, and you can choose your own from More shapes and icons. The SaaS web app and Event-driven services templates are good starting points.

Try it on the canvasNo account needed.

Keep it up to date

An out-of-date architecture diagram is worse than none. Keep it where the team works, share it with edit access, and use History to see who changed what. Copying it as Mermaid lets you keep a text version next to the code.

Questions

What about the C4 model?

C4 is a popular way to draw architecture at four levels of zoom: context, containers, components and code. The advice here fits its first two levels well.

Should I use official cloud icons?

They help when readers know the cloud, and are noise when they don't. For a mixed audience, plain labelled boxes are often clearer.

Keep reading