System Context Diagram in Mermaid
Draw a system context diagram in Mermaid: one system in the middle, the people who use it, and the outside systems it talks to, with the data on every arrow. An online shop example in the free Mermaid live editor.
Step by step
Scope in one picture
- Context diagram. A system context diagram shows one system in the middle and every person and outside system it talks to. It is a quick way to agree on scope. Here is one for an online shop, in 5 lines of Mermaid.
- Diagram type. Clear the Mermaid live editor and type flowchart TD. TD means top down, so the people sit on top and the other systems go below.
flowchart TD
The system
- The system. On the next line, type C[Customer] -->|Order| S((Online shop)). The double round brackets make S a circle, and that circle is the system. The text between the bars is the arrow's label. It names the data that flows, so make it a noun. The diagram now shows one person, one system and the order that passes between them.
C[Customer] -->|Order| S((Online shop))
Users
- Users. Add every type of user. A[Shop admin] -->|Product updates| S points at S again, so the arrow reaches the same circle instead of making a new box.
A[Shop admin] -->|Product updates| S
Other systems
- Other systems. Now add the outside systems. Payment details go both ways, so S <-->|Payment details| P[Payment system] puts an arrowhead at each end. The courier system gets a one-way arrow carrying a delivery request. The diagram now shows the users above, the system in the middle and the outside systems below, with a label on every arrow.
S <-->|Payment details| P[Payment system] S -->|Delivery request| D[Courier system]
Read the scope
- Inside the circle. The Online shop circle has nothing inside it. A context diagram doesn't show the steps inside the system. Those come later, in a process map or a more detailed diagram.
- Outside is out of scope. Everything outside the circle is out of scope. The team doesn't build the payment system. It only exchanges data with it. Show this to stakeholders early and scope arguments end quickly. If someone is missing, add one more line, like the D[Courier system] line, and Mermaid redraws the layout to make room.
Recap
- The rules. The rules: put one system in a circle, users on one side and outside systems on the other, and label every arrow with the data that flows.
Common mistakes
- A new ID for the same system. If you write Shop instead of S on a later line, Mermaid draws a second box. Define S((Online shop)) once, then use only S on every other line.
- Arrows with no label, or a verb as the label. An unlabelled arrow doesn't say what crosses the boundary. Label it with the data as a noun, like Order or Delivery request, not an action like sends.
- Round brackets inside a box label. A label like P[Payment (Stripe)] causes a syntax error, because Mermaid reads the brackets as shape code. Put the label in double quotes: P["Payment (Stripe)"].
- Drawing steps inside the system. Adding boxes like Check stock or Send email turns the diagram into a process map. Keep only the one circle, and put the inner steps in a separate flowchart.
When a business analyst uses this
In a scoping workshop for a new ordering system, a business analyst types the context diagram live in the Mermaid live editor. Stakeholders can see right away which systems the project builds and which it only connects to. The 5 lines of text are kept with the requirements, so the diagram is easy to update after each review.
Questions people ask
How do you make a system context diagram in Mermaid?
Start with flowchart TD. Put your system in a circle with S((Online shop)), then add one line per user or outside system, joined to S by an arrow labelled with the data, like C[Customer] -->|Order| S.
How do you draw a two-way arrow in Mermaid?
Use <--> instead of -->. For example, S <-->|Payment details| P[Payment system] puts an arrowhead at both ends, with the label in the middle.
Does Mermaid have a C4 context diagram?
Yes. Mermaid has a C4Context diagram type, but its documentation marks it as experimental, so its syntax may change. A plain flowchart, like the one here, is a simple and stable alternative.
