Diagrams for digital service teams

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/mermaid/service-team-diagrams.md
Description	Not specified

Source Content

Diagrams for digital service teams

Sixteen Mermaid diagram types, each matched to the one question it answers. Use it to pick the right picture for a service problem — discovery research, a service flow, an architecture, a delivery plan, or a live metric. Every example draws the same service, a parking permit, so the types are easy to compare side by side.

Every diagram follows the house style — monotone-first, with semantic colour only where it teaches, and an inline FontAwesome icon on every node in the types that render them (flowchart, state, class, mindmap, block, ER labels). The icon vocabulary and the full render matrix live in icons-and-surfaces.md.

To see them rendered and agree on the house look, open the gallery at gallery/index.html — point at a card and say “that is the look we want.” That shared reference is what keeps diagrams consistent whether a person or the model draws the next one.

How to choose

The catalog follows the delivery lifecycle: understand users, design the service, show how it connects, plan and deliver, then run and measure. Find the phase, then the question closest to yours.

To answer this question	Reach for	Type	Inline icons
Where does the user feel friction across the whole service?	User journey	journey	No
What are all the parts of this service we have to design and own?	Service map (mindmap)	mindmap	Yes
Of everything we could build, what do we do first?	Prioritisation quadrant	quadrantChart	No
How does a request move from the user to a decision?	Service flow	flowchart	Yes
Which systems talk to each other, and in what order?	Integration sequence	sequenceDiagram	No
What states can a case be in, and how does it move between them?	Case lifecycle (state)	stateDiagram-v2	Yes
Who and what does this service touch?	System context (C4)	C4Context	No
How is this deployed, and what connects to what?	Infrastructure topology	architecture-beta	No
What records do we hold, and how do they relate?	Records model (ER)	erDiagram	Yes
What are the roles, and what can each one do?	Roles and capabilities (class)	classDiagram	Yes
What is the plan, and in what order?	Delivery roadmap (Gantt)	gantt	No
How has the service evolved, and what comes next?	Service phases (timeline)	timeline	No
How does a change reach production?	Release flow (git graph)	gitGraph	No
Where do users fall out of the service?	Drop-out funnel (Sankey)	sankey-beta	No
Is the service getting better?	KPI trend (XY chart)	xychart-beta	No
Which requirements does this service satisfy, and how do we know?	Assurance traceability (requirement)	requirementDiagram	No

All sixteen types render in InteractiveMermaid (vanilla Mermaid 11). The Inline icons column marks which types paint inline FontAwesome icons on their labels — give every node one in those; keep labels plain in the rest. See icons-and-surfaces.md.

Understand users

Discovery — see the whole service through the user’s eyes and decide what matters.

User journey

Where does the user feel friction across the whole service?

Renders as journey in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Mapping an end-to-end experience across many steps and channels.
• You want emotion on the record — the score column shows where it hurts.
• Sharing research with non-technical stakeholders who need the user’s view.

Not the right tool when

• You need branching or decisions — a journey is a single straight track (use a flowchart).
• You need system timing or handoffs (use a sequence diagram).

journey
    title Apply for a parking permit
    section Find the service
      Search online: 3: Resident
      Check eligibility: 4: Resident
    section Apply
      Create an account: 2: Resident
      Answer questions: 3: Resident
      Upload proof of address: 1: Resident
      Pay the fee: 3: Resident
    section Receive
      Get confirmation: 5: Resident
      Permit arrives: 5: Resident

What to notice: The low scores cluster around account creation and proof of address — that is where to spend design effort.

Service map (mindmap)

What are all the parts of this service we have to design and own?

Renders as mindmap in InteractiveMermaid. Carries inline FontAwesome icons — give every actor, system, and outcome one.

Reach for it when

• Early discovery, laying out users, channels, systems, and policy at once.
• Building shared vocabulary before anyone commits to a flow.
• A living inventory of what a service is made of.

Not the right tool when

• You need order or sequence — a mindmap has none (use a flowchart or timeline).
• You need links between branches — a mindmap is a strict tree, not a graph (use a flowchart).

mindmap
  root((Parking permit service))
    fas:fa-users Users
      Residents
      Businesses
      Carers
    fas:fa-mobile-screen Channels
      Online
      Phone
      Paper form
    fas:fa-desktop Systems
      Case management
      Payments
      Notifications
    fas:fa-clipboard-list Policy
      Eligibility rules
      Fees and refunds

What to notice: Four branches, one glance: users, channels, systems, policy. Mindmaps render inline icons, so each branch carries its own. Anything not on a branch is a gap in the plan.

Prioritisation quadrant

Of everything we could build, what do we do first?

Renders as quadrantChart in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Ranking a backlog by two forces at once, usually impact against effort.
• Making a prioritisation call visible and defensible in a workshop.
• Any two-axis trade-off — value vs. risk, reach vs. cost.

Not the right tool when

• You have one dimension only (use a sorted list or a bar chart).
• The points need exact values — a quadrant shows position, not precision.

quadrantChart
    title Backlog prioritisation
    x-axis Low effort --> High effort
    y-axis Low impact --> High impact
    quadrant-1 Major projects
    quadrant-2 Do now
    quadrant-3 Reconsider
    quadrant-4 Quick wins
    Online payments: [0.35, 0.9]
    Address lookup: [0.25, 0.6]
    Accessibility fixes: [0.4, 0.85]
    Legacy migration: [0.8, 0.55]
    Chatbot: [0.7, 0.25]

What to notice: Top-left is the sweet spot: high impact, low effort. Accessibility fixes and online payments land there — do them now.

Design the service

Design — turn research into a flow, the handoffs behind it, and the states a case moves through.

Service flow

How does a request move from the user to a decision?

Renders as flowchart in InteractiveMermaid. Carries inline FontAwesome icons — give every actor, system, and outcome one.

Reach for it when

• Showing a process with a real decision or branch in it.
• The lesson is what the user does versus what the service does — group by that boundary.
• The default diagram; when unsure, this is usually the right one.

Not the right tool when

• There is no branching, just a felt experience (use a user journey).
• The point is timing between systems (use a sequence diagram).

flowchart TD
    subgraph Resident["fas:fa-user What the resident does"]
      Start(["fas:fa-pen-to-square Start application"]) --> Answer["fas:fa-pen-to-square Answer questions"] --> Submit["fas:fa-upload Submit"]
    end
    subgraph Service["fas:fa-gear What the service does"]
      Validate["fas:fa-magnifying-glass Validate details"] --> Check{"Eligible?"}
      Check -->|Yes| Grant["fas:fa-ticket Issue permit"]
      Check -->|No| Refuse["fas:fa-hand Explain refusal"]
    end
    Submit -->|on submit| Validate

    style Resident fill:#eef2ff,stroke:#6366f1,color:#1e1b4b
    style Service fill:#eff6ff,stroke:#2563eb,color:#172554
    style Check fill:#fef9c3,stroke:#ca8a04,color:#422006
    style Grant fill:#dcfce7,stroke:#16a34a,color:#14532d
    style Refuse fill:#fee2e2,stroke:#dc2626,color:#450a0a

What to notice: Colour and shape carry the story: the tinted zones split what people do from automation, the diamond is the one decision, and green versus red is the outcome — each node led by an inline icon.

Integration sequence

Which systems talk to each other, and in what order?

Renders as sequenceDiagram in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Designing or documenting an integration across services.
• Strict time order is the point — message one must precede message two.
• Debugging a handoff: which call fires when, and what replies.

Not the right tool when

• The reader needs the user’s emotional arc (use a user journey).
• You are showing allowed states rather than a single run (use a state diagram).

sequenceDiagram
    actor Resident as Resident
    participant Web as Web app
    participant Case as Case system
    participant Pay as Payments
    participant Notify as Notifications
    Resident->>Web: Submit application
    Web->>Case: Create case
    Case->>Pay: Request fee
    Pay-->>Resident: Take payment
    Pay-->>Case: Payment confirmed
    Case->>Notify: Send confirmation
    Notify-->>Resident: Email and SMS

What to notice: Read top to bottom as time — the resident only ever touches the web app and the payment step; every other hop is system-to-system. Sequence diagrams can’t render inline icons, so the message arrows carry the meaning.

Case lifecycle (state)

What states can a case be in, and how does it move between them?

Renders as stateDiagram-v2 in InteractiveMermaid. Carries inline FontAwesome icons — give every actor, system, and outcome one.

Reach for it when

• Modelling the lifecycle of an application, case, order, or account.
• You need to show allowed transitions — and which ones are not allowed.
• There are loops back: sent for more info, then resubmitted.

Not the right tool when

• You are showing one specific run through the system (use a sequence diagram).
• The states are really process steps with no return paths (use a flowchart).

stateDiagram-v2
    state "fas:fa-pen-to-square Draft" as Draft
    state "fas:fa-upload Submitted" as Submitted
    state "fas:fa-magnifying-glass Under review" as UnderReview
    state "fas:fa-triangle-exclamation More info needed" as MoreInfo
    state "fas:fa-circle-check Granted" as Granted
    state "fas:fa-circle-xmark Refused" as Refused
    [*] --> Draft
    Draft --> Submitted : resident submits
    Submitted --> UnderReview : assigned
    UnderReview --> MoreInfo : needs evidence
    MoreInfo --> UnderReview : evidence supplied
    UnderReview --> Granted : approved
    UnderReview --> Refused : rejected
    Granted --> [*]
    Refused --> [*]

What to notice: State diagrams render inline icons too — the check marks the granted exit and the cross marks the refused exit, while the warning-flagged ‘more info needed’ state is the loop where cases stall: one way out of review, two ways in.

Show how it connects

Architecture — make the moving parts, their boundaries, and their records legible to anyone.

System context (C4)

Who and what does this service touch?

Renders as C4Context in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Setting the scene: the service as one box among the people and systems around it.
• Onboarding someone who needs the big picture before any detail.
• Naming external dependencies and who owns them.

Not the right tool when

• You need what is inside the box (use a C4 container diagram or architecture diagram).
• The audience wants infrastructure, not logical boundaries (use an architecture diagram).

C4Context
    title System context - Parking permit service
    Person(resident, "Resident", "Wants a permit")
    System(permit, "Permit service", "Apply, pay, receive")
    System_Ext(pay, "Payments platform", "Card payments")
    System_Ext(notify, "Notifications", "Email and SMS")
    System_Ext(dvla, "Vehicle registry", "Vehicle checks")
    Rel(resident, permit, "Applies using")
    Rel(permit, pay, "Takes payment via")
    Rel(permit, notify, "Sends messages via")
    Rel(permit, dvla, "Verifies vehicle with")

What to notice: C4 draws the person and the systems as different shapes for free — that shape difference alone separates our permit service from the external payments, notifications, and vehicle-registry systems (C4 renders no inline icons).

Infrastructure topology

How is this deployed, and what connects to what?

Renders as architecture-beta in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Showing the runtime shape: services, stores, queues, and the edges between them.
• The audience is technical and wants the deployment picture.
• You want grouping by environment or cloud boundary.

Not the right tool when

• The audience is non-technical (use a C4 context diagram).
• You want logical ownership rather than runtime topology (use a C4 context diagram).

architecture-beta
    group cloud(cloud)[Cloud]
    service web(server)[Web app] in cloud
    service api(server)[API] in cloud
    service db(database)[Case store] in cloud
    service queue(disk)[Message queue] in cloud
    web:R --> L:api
    api:R --> L:db
    api:B --> T:queue

What to notice: This type ships with built-in shape icons — server, database, disk, cloud — so each node’s role reads before its label (inline FontAwesome does not apply here). The cloud box shows what is ours to run.

Records model (ER)

What records do we hold, and how do they relate?

Renders as erDiagram in InteractiveMermaid. Carries inline FontAwesome icons — give every actor, system, and outcome one.

Reach for it when

• Modelling durable data: the nouns the service stores and their relationships.
• Agreeing a data model before anyone writes a migration.
• Showing ownership and cardinality — one application, many documents.

Not the right tool when

• You are showing a process or flow (use a flowchart or sequence diagram).
• The relationships change over time — ER shows structure, not lifecycle.

erDiagram
    RESIDENT ||--o{ APPLICATION : "fas:fa-paper-plane submits"
    APPLICATION ||--|| PERMIT : "fas:fa-ticket results in"
    APPLICATION ||--o{ DOCUMENT : "fas:fa-paperclip includes"
    CASEWORKER ||--o{ APPLICATION : "fas:fa-magnifying-glass reviews"

What to notice: The crow’s feet carry the rule — one resident, many applications; one application, exactly one permit — and ER renders an inline icon on each relationship label, so the verb reads before you trace the line.

Roles and capabilities (class)

What are the roles, and what can each one do?

Renders as classDiagram in InteractiveMermaid. Carries inline FontAwesome icons — give every actor, system, and outcome one.

Reach for it when

• Modelling responsibilities: what each actor or object is allowed to do.
• Showing a domain model with methods, not just data.
• Documenting an API or object model for engineers.

Not the right tool when

• The audience is non-technical (use a flowchart or journey).
• You only have data, no behaviour (use an ER diagram).

classDiagram
    class Application["fas:fa-pen-to-square Application"] {
      +submit()
      +withdraw()
    }
    class Caseworker["fas:fa-user-tie Caseworker"] {
      +review()
      +requestInfo()
      +decide()
    }
    Caseworker --> Application : processes

What to notice: Class diagrams render inline icons too — the verbs are the point: the caseworker can decide, while the application can only be submitted or withdrawn.

Plan and deliver

Delivery — sequence the work and show how change reaches production.

Delivery roadmap (Gantt)

What is the plan, and in what order?

Renders as gantt in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Sequencing phases and tasks against real dates.
• Showing dependencies — this task starts after that one.
• A delivery plan a sponsor can read at a glance.

Not the right tool when

• Dates are unknown or irrelevant (use a timeline).
• The plan has branches or decisions, not a fixed schedule (use a flowchart).

gantt
    title Delivery roadmap
    dateFormat YYYY-MM-DD
    section Discovery
      User research     :a1, 2026-01-06, 20d
      Service map       :a2, after a1, 10d
    section Alpha
      Prototype         :b1, after a2, 25d
      Usability testing :b2, after b1, 15d
    section Beta
      Build MVP         :c1, after b2, 40d
      Private beta      :c2, after c1, 20d

What to notice: The critical line runs straight down the ‘after’ chain — every task starts after the last, so every slip in discovery pushes beta to the right.

Service phases (timeline)

How has the service evolved, and what comes next?

Renders as timeline in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Showing phases or milestones without needing exact dates.
• Telling the story of a service across discovery, alpha, beta, live.
• A lightweight roadmap for a non-technical audience.

Not the right tool when

• You need task dependencies or durations (use a Gantt chart).
• You need exact dates on each item (use a Gantt chart).

timeline
    title Service phases
    Discovery : Understand users : Map the service
    Alpha : Prototype : Test the riskiest assumptions
    Beta : Build the MVP : Private then public beta
    Live : Continuous improvement : Meet the service standard

What to notice: Each phase names its own purpose, not just its point in time — so the reader sees not just when but why the service changed shape.

Release flow (git graph)

How does a change reach production?

Renders as gitGraph in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Explaining a branching and release strategy to a team.
• Showing where a change is cut, reviewed, merged, and tagged.
• Onboarding engineers to how the repo is run.

Not the right tool when

• The audience does not use git (use a flowchart).
• You are explaining a process, not branch topology (use a flowchart).

gitGraph
    commit id: "baseline"
    branch feature
    checkout feature
    commit id: "build form"
    commit id: "add validation"
    checkout main
    merge feature
    commit id: "release" tag: "v1.1"

What to notice: Work happens on a branch and lands on main in one merge — the version tag marks what actually shipped.

Run and measure

Live — watch where users drop out and whether the service is getting better.

Drop-out funnel (Sankey)

Where do users fall out of the service?

Renders as sankey-beta in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Showing volume flowing through a funnel, with the leaks called out.
• Turning analytics into a picture: how many started, finished, abandoned.
• Making a conversion problem impossible to ignore.

Not the right tool when

• You need a trend over time (use an XY chart).
• The categories are not a flow — you are comparing independent amounts (use a bar chart).

sankey-beta
Visited,Started application,1000
Started application,Completed application,620
Started application,Abandoned,380
Completed application,Paid,540
Completed application,Payment failed,80
Paid,Permit issued,540

What to notice: Sankey needs no icons — band width does the encoding. The fat Abandoned band after Started is the whole story: nearly two in five who start never finish.

KPI trend (XY chart)

Is the service getting better?

Renders as xychart-beta in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Tracking a metric over ordered buckets — months, weeks, sprints.
• Showing a trend a sponsor can read in two seconds.
• Comparing a count and a rate on the same axis.

Not the right tool when

• The buckets are not ordered (use a bar comparison or table).
• You are showing where volume goes, not how it trends (use a Sankey).

xychart-beta
    title "Completion rate by month"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Percent completed" 0 --> 100
    bar [58, 61, 66, 70, 74, 79]
    line [58, 61, 66, 70, 74, 79]

What to notice: The line only goes up and to the right — completion has climbed every month since launch.

Assurance traceability (requirement)

Which requirements does this service satisfy, and how do we know?

Renders as requirementDiagram in InteractiveMermaid. Notation-only — this type does not paint inline icons, so keep every label plain.

Reach for it when

• Tracing requirements to the components that satisfy them.
• Assurance, audit, or accreditation work — showing coverage and risk.
• Making a verification method explicit for each requirement.

Not the right tool when

• You just need a checklist with no traceability (use a table).
• You are showing a process or flow (use a flowchart).

requirementDiagram
    requirement accessibility {
      id: 1
      text: Meets WCAG 2.2 AA
      risk: high
      verifymethod: test
    }
    element permit_form {
      type: component
    }
    permit_form - satisfies -> accessibility

What to notice: Every requirement carries its own risk and how it will be verified — the arrow is the evidence trail.

Keep every diagram lint-clean

Every block above passes the skill’s linter. Before shipping a new diagram, run it:

python3 ~/.copilot/skills/technical-writing/scripts/mermaid_lint.py /path/to/file.md

The flowchart in this catalog still obeys the flowchart rules in diagram-principles.md: grouped by people versus automation, seven nodes or fewer, top-down, and colored only on the two outcome nodes. The other types are reference-only shapes — a journey is one straight track, an ER diagram holds no flow — so those flowchart rules do not apply to them.