Mermaid Diagram Types

Reference page, not course content. Mermaid 11.17.2 ships far more than flowcharts — this shows the types worth knowing, each with a note on where it would actually be useful.

Everything renders from a plain ```mermaid fence. No imports, no extra dependencies.

---

1. Flowchart — the workhorse

What we already use everywhere. Boxes, arrows, classDef styling.

graph LR
  A["Business driver"] --> B["Quality requirement"] --> C["Architecture decision"]

  classDef s1 fill:#D9695B,stroke:#B4483A,stroke-width:2px,color:#ffffff
  classDef s2 fill:#E8A33D,stroke:#C4832A,stroke-width:2px,color:#ffffff
  classDef s3 fill:#7D9A4E,stroke:#5F7A38,stroke-width:2px,color:#ffffff
  class A s1
  class B s2
  class C s3

Use for: anything structural. The default choice.

---

2. Sequence diagram — who calls whom, in what order

sequenceDiagram
  autonumber
  participant U as Customer
  participant A as Support agent
  participant R as Retrieval
  participant M as Model
  participant H as Human

  U->>A: asks a question
  A->>R: fetch relevant docs
  R-->>A: passages
  A->>M: question + passages
  M-->>A: draft answer + confidence
  alt confident enough
    A-->>U: answer
  else below threshold
    A->>H: hand off with context
    H-->>U: answer
  end

Use for: Module 5 (agent tool calls), Module 6 (guardrail placement in the request path). Far better than a flowchart when ordering and hand-offs are the point.

---

3. State diagram — lifecycle and transitions

stateDiagram-v2
  [*] --> Proposed
  Proposed --> Accepted: sponsor endorses
  Proposed --> Rejected: fails review
  Accepted --> Superseded: a later ADR replaces it
  Accepted --> Deprecated: no longer applies
  Rejected --> [*]
  Superseded --> [*]
  Deprecated --> [*]

Use for: Module 9 — ADR status is exactly a state machine. Also incident lifecycle, approval flows.

---

4. C4 context diagram — purpose-built for architecture

C4Context
  title System context — AI support platform

  Person(customer, "Customer", "Raises a support request")
  Person(agent, "Support agent", "Handles escalations")

  System(platform, "AI Support Platform", "Retrieval, agent, handoff")

  System_Ext(zendesk, "Zendesk", "Ticketing")
  System_Ext(monolith, "Rails monolith", "Scheduling, billing")
  System_Ext(provider, "Model provider", "External inference")

  Rel(customer, platform, "asks")
  Rel(platform, zendesk, "reads/writes tickets")
  Rel(platform, monolith, "takes actions")
  Rel(platform, provider, "sends prompts")
  Rel(platform, agent, "hands off to")

Use for: Module 1 capstone — this is the C4 Level 1 diagram the capstone asks for, and Mermaid does it natively.

---

5. Quadrant chart — prioritising by two axes

quadrantChart
  title Requirements by value and risk
  x-axis "Low architectural risk" --> "High architectural risk"
  y-axis "Low business value" --> "High business value"
  quadrant-1 "Do first"
  quadrant-2 "Watch closely"
  quadrant-3 "Ignore"
  quadrant-4 "Cheap wins"
  "Cost per interaction": [0.75, 0.90]
  "Data residency": [0.88, 0.78]
  "Response latency": [0.35, 0.65]
  "Answer accuracy": [0.70, 0.85]
  "Agent tone": [0.20, 0.18]
  "Multi-language": [0.45, 0.30]

Use for: Module 2 — the Utility Tree prioritises by business value × architectural risk. This is that, drawn.

---

6. Mindmap — decomposition

mindmap
  root((Architect's remit))
    Decides
      Cross-team structure
      Technology constraints
      Where data may live
    Advises on
      Sequencing
      Buy vs build
      Risk
    Does not decide
      Implementation choices
      Staffing
      Product scope
      Release dates

Use for: Module 1 — the architecture charter. Also breaking a domain into bounded contexts.

---

7. Timeline — a roadmap without dates

timeline
  title Architecture practice, first six months
  Month 1 : Read the data
          : Talk to all stakeholders
  Month 2 : Business-value brief
          : Architecture charter
  Month 3 : First ADRs
          : Requirements catalog
  Month 4-6 : Reference architecture
            : Migration sequence

Use for: Module 3 (technology roadmap), Module 9 (what governance to introduce, and when).

---

8. Gantt — sequencing under real constraints

gantt
  title Migration sequence under zero spare capacity
  dateFormat YYYY-MM-DD
  axisFormat %b

  section Strangler migration
  Existing work (untouched)   :done,    m1, 2026-01-01, 120d
  section AI platform
  Retrieval over docs         :active,  a1, 2026-02-01, 60d
  Evaluation harness          :         a2, after a1, 45d
  Agent actions (gated)       :         a3, after a2, 60d
  section Decisions
  Buy vs build reviewed       :milestone, after a2, 0d

Use for: Module 10 — sequencing a migration that ships value continuously. Milestones mark decision points, not just deliveries.

---

9. Git graph — branching and strangler migration

gitGraph
  commit id: "monolith"
  commit id: "traffic 0%"
  branch extraction
  checkout extraction
  commit id: "new service"
  commit id: "shadow traffic"
  checkout main
  merge extraction id: "traffic 10%"
  commit id: "traffic 35%"
  branch next-slice
  checkout next-slice
  commit id: "second service"
  checkout main
  merge next-slice id: "traffic 60%"

Use for: Module 10 — strangler-fig migration is literally this shape.

---

10. Sankey — where cost or volume actually goes

sankey-beta
Total tickets,Answerable from docs,4560
Total tickets,Needs a human,7440
Answerable from docs,Deflected by platform,3192
Answerable from docs,Escalated anyway,1368

Use for: Module 2 and 6 — showing where volume or spend actually flows. Much stronger than a table when the point is proportion.

---

11. ER diagram — data relationships

erDiagram
  CUSTOMER ||--o{ TICKET : raises
  TICKET ||--o{ MESSAGE : contains
  TICKET }o--|| AGENT : "assigned to"
  TICKET ||--o| JOB : "may reference"
  MESSAGE }o--o| EMBEDDING : "indexed as"

Use for: Module 4 — what actually gets embedded, and which entities carry personal data.

---

12. Block diagram — layered stack

block-beta
  columns 3
  gateway["API gateway"]:3
  cache["Semantic cache"] router["Model router"] guard["Guardrails"]
  retrieval["Retrieval"]:2 store["Vector store"]
  obs["Observability + cost attribution"]:3

  style gateway fill:#5B8FB9,stroke:#4A7A9E,color:#fff
  style cache fill:#4E9A94,stroke:#3B7A75,color:#fff
  style router fill:#4E9A94,stroke:#3B7A75,color:#fff
  style guard fill:#E8A33D,stroke:#C4832A,color:#fff
  style retrieval fill:#D9695B,stroke:#B4483A,color:#fff
  style store fill:#D9695B,stroke:#B4483A,color:#fff
  style obs fill:#7C7C7C,stroke:#5E5E5E,color:#fff

Use for: Module 4 — the AI stack drawn as layers rather than a flow.

---

13. User journey — experience, with sentiment

journey
  title Getting an answer out of support
  section Self-service
    Search the docs: 2: Customer
    Give up: 1: Customer
  section Raise a ticket
    Describe the problem: 3: Customer
    Wait: 1: Customer
  section Resolution
    Agent replies: 4: Customer, Agent
    Problem solved: 5: Customer

Use for: Module 2 — stakeholder experience, where the scores make the pain visible rather than asserted.

---

14. Pie — proportions, sparingly

pie showData
  title Where support volume goes
  "Answerable from docs" : 38
  "Needs a human" : 62

Use for: one number worth emphasising. Resist otherwise — a sentence usually does the job.

---

Which of these to actually reach for

Diagram	Reach for it when
Flowchart	Default. Anything structural
Sequence	Ordering and hand-offs are the point
State	Something has a lifecycle — ADRs, tickets, approvals
C4 Context	The capstone’s Level 1 diagram
Quadrant	Prioritising on two axes
Mindmap	Decomposing a remit or a domain
Timeline / Gantt	Roadmaps; Gantt when dependencies matter
Git graph	Branching and strangler migrations
Sankey	Proportions of flow — volume, spend
ER	Data relationships and what gets embedded
Block	A layered stack rather than a flow
Journey	Experience with sentiment attached
Pie	Almost never

The width rule in CONTENT_AND_STYLE_GUIDE.md §6 applies to all of them: past about five boxes across, everything shrinks. Sequence and state diagrams grow downward, which is why they tolerate more detail than a flowchart does.