Simple Conventions for System Architecture Diagrams

David Booth <dbooth@w3.org>

$Revision: 1.7 $ of $Date: 2002/10/21 15:13:26 $ by $Author: dbooth $

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.

---