Simple Conventions for System Architecture Diagrams

This document proposes some very simple
conventions for system architecture diagrams.

Status of This Document

This document represents the views of the
author only. It has no official
status. Comments are welcome.

Identify the Actors, Artifacts and Actions

Clearly distinguish the actors, the
artifacts and the actions in your system
diagram. To find them, look for nouns
and verbs in your use cases. The
verbs are actions, the nouns are either actors or
artifacts. Here are some
simple, functional definitions that distinguish them.

Note: This document is not
suggesting that you standardize on these particular icons or visual
symbols, nor on the terminology of "actor", "artifact" and
"action". These particular terms and
icons were only chosen to help explain the ideas.

Actors
(or "Roles" or "Components" or "Agents") -- Who or
what performs the actions that occur?

Actors are physical or conceptual entities
that perform actions. For example: people, companies, machines,
running software, etc. In a diagram,
they are the nodes. If you can, use
non-rectangular shapes for actors.
Example icons:

Artifacts (or "Documents") -- What information is
transferred?

Artifacts are just pieces of information. They do not perform actions. They are used to label the actions, to
indicate the information that is transferred, or to indicate input
or output. To visually represent an
artifact, use a page icon, box or other icon that clearly suggests
"information" or "document". Don't
use a round or oval shape, or your artifact will look like an
actor.

Actions
(or "Responsibilities") -- What actions are performed?

Also called "responsibilities". These are verbs.
They may be as simple as sending or receiving information. In a diagram, actions are arcs that
connect the nodes. Sometimes it's
helpful to label the arc with the action, the artifact (data) that
is transferred, or both. Examples of
action arcs labeled with action names:

Example diagram, where the action is also
labeled with the artifact (a Key) that is transferred:

There are two actors: a person and a
computer. The person performs a
login action, sending an artifact that represents a key.

Client-Server Diagrams

If the diagram shows a Client-Server
relationship, place the Client on the left and Server on the
right. This is a convention that
makes the diagram easier to parse.
(It is analogous to the hot-on-the-left, cold-on-the-right
convention for water faucets. The
faucets will work the same either way, but it avoids user confusion
if you follow the convention.)

Grouping Nodes

Use dotted lines or shading to indicate
grouping of multiple nodes into a larger, logical node.