# Block diagram

Not every diagram needs a notation. A block diagram is boxes, arrows and labels, and it is the honest choice when the shapes carry no special meaning.

Draw it as text if it will change, and on a canvas if the layout is the message.

---

## When to reach for one

* Explaining a system to a non-technical audience.
* Early design work, before the components are real enough for a notation.
* Slides and summaries, where a strict notation gets in the way.

---

## How to draw it in Capable

| **Route**     | **Use when**                                            |
| ------------- | ------------------------------------------------------- |
| Mermaid or D2 | Automatic layout, so a new box does not mean redrawing. |
| draw.io       | Precise placement, grouping and colour.                 |
| Excalidraw    | When looking provisional is the point.                  |

---

## A worked example

Boxes, a group and labelled arrows:

![Block diagram](https://help.gocapable.com/images/att1417478183.svg)

The source, which you can paste into a new diagram and edit:

```
direction: right

source: Source systems {
  crm: CRM
  billing: Billing
}
pipeline: Ingest pipeline
store: Warehouse {
  shape: cylinder
}
bi: Dashboards

source.crm -> pipeline: nightly export
source.billing -> pipeline: hourly
pipeline -> store: load
store -> bi: query
```

---

## A few things that catch people out

* Label the arrows. Unlabelled arrows are the reason block diagrams get dismissed as vague.
* Group related boxes rather than adding more arrows.
* If you find yourself inventing shape meanings, switch to a real notation.

---

## Related

[UML diagramsThe UML types you can draw, and what to use for each.](https://help.gocapable.com/diagrams/uml-diagrams.html)

[C4 modelContext, containers, components, in that order.](https://help.gocapable.com/diagrams/c4-model.html)

[ExamplesWorking diagrams you can copy.](https://help.gocapable.com/diagrams/examples.html)

---

_Cheap to change means it stays true._