UML and C4 diagrams¶
UML has fourteen kinds of diagram. Most people draw about three of them, on a whiteboard, and that's fine. The UML library has the shapes those three need, in the same hand-drawn line as everything else, plus the ten relationships people actually draw between boxes.
In the Library panel, the UML library comes in four groups: Shapes, Boxes, Sequence and Relationships.
Shapes¶
| Shape | What it's for |
|---|---|
| Actor | Someone or something outside the system that uses it: a person, another system, a device |
| Initial Node | Where an activity starts |
| Final Node | Where the whole activity ends |
| Flow Final | Where one flow ends while the others carry on |
| Terminate | Where a state machine ends: a transition into it stops everything |
| Fork / Join Bar | Where a flow splits into parallel flows, or where they meet again |
| Note | A comment, with its corner folded over |
| Package | A named group of things, with a tab on top |
A few of them behave in ways worth knowing:
- The actor, the nodes, Terminate and the bar are named underneath. A name under the actor has room for a couple of words before it wraps, so "Customer Service" stays on one line.
- Arrows meet Terminate at the tips of its X. Its only connection points are the four ends of its arms, so an arrow always touches the X instead of stopping in the empty space between two arms.
- Arrows meet the round nodes on their circle. Initial Node, Final Node and Flow Final each have eight connection points, all on the circle itself: at the top, bottom and sides, and halfway between. An arrow touches the circle from whichever direction it comes, instead of stopping short at a corner of the shape's box.
- The fork / join bar keeps its thickness. It only shows its two end handles, so you can make it longer but not fatter. Want it bolder? Give it a heavier line weight. It lies flat; turn it a quarter turn for a vertical bar. Each long side takes several flows.
- The Note's folded corner and the Package's tab keep their size. Make a note bigger and the fold stays a fold rather than becoming a landslide. The Package's tab gets a little taller as the package grows, which looks right.
The other everyday UML shapes are already in Basic. Search for uml in the
Library panel and they turn up with the rest: the Circle for a use case, the
Rounded Rectangle for a state or an action, the Diamond for a decision, the
Cube for a node and the Cylinder for a database.
Boxes¶
| Box | What you get |
|---|---|
| Class | A class name, then a row for its attributes and a row for its operations |
| Interface | «interface» and a name, then a row for its operations |
| Enumeration | «enumeration» and a name, then its values, one per line |
| Database Entity | A table's name, then its fields, one per line |
| System Boundary | A box titled System, to put a use case diagram's use cases in |
The first four are ordinary tables and the System Boundary is an ordinary container, so there's nothing special to learn. Each one starts with placeholder text: type over it. Double-click a cell to type in it, and Tab moves you on to the next one.
Another attribute? Press Enter for a new line in the same cell, which is how UML likes it anyway: one compartment, one thing per line. The row gets taller to fit. If you really do want another row, press Tab in the last cell and you get one at the bottom, or click a cell and use Format › Complex Shape (or right-click) to insert a row or column exactly where you want it.
UML has two old habits for class names. Set the name in italics for an abstract
class. Underline it, written as order1 : Order, for an object rather than a class.
Put use cases inside the System Boundary and their actors outside. That's the whole rule.
Relationships¶
The Relationships group has the ten lines people draw between UML boxes. Each one is an ordinary connector with a particular line and endings. The way you draw it matters, because each ending means something at its end:
| Relationship | Its line | Draw it from… | …to |
|---|---|---|---|
| Association | Plain line | Either class | The other |
| Inheritance | Hollow Arrow at the end | The child class | Its parent |
| Implements | Dashed, Hollow Arrow at the end | The class | The interface it implements |
| Dependency | Dashed, Arrow at the end | The class that uses something | The thing it uses |
| Aggregation | Diamond at the start | The whole | A part that can exist without it |
| Composition | Filled Diamond at the start | The whole | A part that belongs to it alone |
| Message | Straight, Filled Arrow at the end | The caller | The one it calls |
| Reply | Straight, dashed, Arrow at the end | The one that was called | The caller |
| Async Message | Straight, Arrow at the end | The sender | The receiver |
| One to Many | One and Only One at the start, Zero or Many at the end | The one, such as a customer | The many, such as its orders |
You don't have to memorise that. In Format › UML Relationship and the right-click menu, hovering over a relationship tells you which way to draw it.
The class and database relationships run with right angles; the three messages, from sequence diagrams, are straight. Async Message doubles as a directed association: draw it from the class that knows to the class it knows about.
There are three ways to use them:
- Click a tile, then draw. The Connector tool is ready, and the next connector you draw has that relationship's look. Colour still comes from the toolbar.
- Drag a tile onto the page. You get a short connector with that look, right where you let go. Then drag each end onto a shape to connect it. Grab the tile anywhere, not just by its line, which is very thin.
- Change lines you've already drawn. Select them and choose Format ▸ UML Relationship, or right-click a connector. Every selected connector takes the new look and keeps its route.
The result is an ordinary connector. Change an ending later and it simply changes; nothing checks that it's still valid UML. We trust you.
Sequence diagrams¶
A sequence diagram shows who calls whom, in order, down the page. The Sequence group has the two kinds of participant:
| Shape | What it's for |
|---|---|
| Lifeline | Something taking part: an object, a service, a system. Its name goes in the box at the top. |
| Actor Lifeline | A person or other actor, drawn as a stick figure with the name below it. |
Put the lifelines side by side along the top, then draw Message, Reply and Async Message between them, top to bottom in the order things happen.
- A message attaches anywhere along the dashed line, not just at fixed points. Bring an end near the line and the line lights up; let go and the end stays right there.
- Messages come out level. As an end comes close to level with the other end, it snaps level, so the message runs straight across. Keep dragging past it if you really want a slope.
- A call to itself is a message from a lifeline back to the same lifeline. It loops out to the side and back.
- Move a message up or down: Cmd-drag it, or select it and use the arrow keys. Both ends slide along their lifelines together, so it stays level and attached, and it stops where the shorter dashed line ends.
- Run out of room? Drag the bottom handle down. The line gets longer and every message stays exactly where it is. Dragging the top edge moves the head, and the messages still stay put. A lifeline can't be made shorter than its lowest message.
- Move a lifeline and its messages' ends come with it. Delete one and its messages stay where they were drawn, no longer attached.
- End a lifeline with an X when its participant is destroyed or stops taking part: right-click the lifeline and choose Ends in Destroy Mark, or turn it on in Shape Properties. The X sits on the end of the dashed line and stays there as you lengthen or move the lifeline. Choose it again to take the X off. (The X in the Shapes group is Terminate, for state machines. It wouldn't follow a lifeline.)
Clicks beside the dashed line go to whatever is behind it, so a lifeline never gets in the way of selecting a message. A lifeline's head always stays at the top, so it can't be flipped.
Frames and fragments¶
The Sequence group also has the frames UML draws around parts of a sequence diagram:
| Shape | What it's for |
|---|---|
| Frame | The whole diagram, named in its corner tag, as sd Login |
| Alt Fragment | A choice between alternatives. Draw a dashed line across it between the branches, and write each branch's condition in square brackets |
| Loop Fragment | Messages that repeat, with the condition in square brackets, as [for each item] |
| Opt Fragment | Messages that happen only when a condition holds, as [in stock] |
Draw your lifelines and messages first, then drag a frame over them. It goes behind what's
already on the page, so it never covers your messages. Type over the tag to name it, such
as sd Checkout; keep alt, loop and opt as they are, since they're UML's own words.
Each one is an ordinary container with its title in a corner tag. A lifeline that runs through a fragment isn't inside it, so moving a fragment moves only the fragment.
Drawing C4 diagrams¶
C4 is the other way people draw software architecture, and it needs nothing new. There's no C4 library; here's the recipe with what's already there:
- Systems and containers are boxes. Use Basic's Square, stretched to fit, with
a three-line label: the name in bold, then its type in brackets, such as
[Container: Django], then a short description. - People are busts. The Biz library's people, such as Founder, Engineer and Support Agent, are the head-and-shoulders figures C4 uses.
- The boundary is a container. Draw a System Boundary (from UML's Boxes) or any container around one system's boxes, and give it the system's name.
- Arrows say what flows. Draw a connector and double-click it to label it, say "Reads orders from [JSON/HTTPS]".
Have a C4 stencil from Visio? Import it as a library and its shapes come across with their name, type and description already in place. See Visio stencils.
UML is a registered trademark of the Object Management Group. These shapes are not endorsed by it.