Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 39 ยท Getting Started

Modeling Tools and Diagrams as Code

Compare whiteboards, drawing tools, full modeling suites and text-based tools such as Mermaid and PlantUML, and learn the diagram-as-code workflow used in this course.

You can draw UML on a whiteboard, in a drawing program, in a full modeling suite, or by writing a few lines of text and letting a tool render the picture. Each choice trades speed against rigor. This lesson compares the options and introduces the diagram-as-code approach, because every diagram in this course is written that way.

Four kinds of tools

Kind Examples Strength Weakness
Whiteboard or paper marker, tablet, sticky notes Fastest for sketching and discussion Not searchable, hard to share
General drawing tools draw.io (diagrams.net), Lucidchart, Excalidraw, Figma Full layout control, shape libraries Diagrams are pictures; nothing checks they are valid UML
Text-to-diagram tools Mermaid, PlantUML, D2, Structurizr DSL Versionable, diffable, reviewable in pull requests Less control over exact layout
Full modeling suites Enterprise Architect, Visual Paradigm, MagicDraw, Papyrus One model behind all diagrams, code generation, validation Heavy, costly, steeper learning curve

There is no best tool. A common combination on real teams: whiteboard for the first sketch, text-based diagrams in the repository for anything that should stay up to date.

Why diagrams as code

When the diagram lives as text next to your source code:

  • It goes through version control. You can see who changed a relationship and why.
  • Reviews work. A pull request that changes code and its diagram is one reviewable unit.
  • Search works. grep finds every diagram mentioning Invoice.
  • Layout is automatic. You describe relationships and the engine draws them.
  • Diagrams can be generated by scripts, which you will do in From Models to Code.

Mermaid in two minutes

Mermaid is a JavaScript library that turns text into diagrams. It is built into many Markdown renderers (GitHub, GitLab, many documentation sites, this one). A diagram starts with a keyword naming its type, followed by statements.

classDiagram
    class Animal {
        +String name
        +eat()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

Mermaid supports classDiagram, sequenceDiagram, stateDiagram-v2, flowchart (we use it for activity-style flows), erDiagram, gantt, and more. It does not cover all 14 UML diagram types natively; where it lacks one (use case, deployment, component), we draw the same idea with a flowchart and note the UML meaning. Mermaid is also lenient about strict UML rules, so you are responsible for modeling correctly.

A sequence diagram

sequenceDiagram
    actor User
    participant Web
    participant API
    User->>Web: click "Buy"
    Web->>API: POST /orders
    API-->>Web: 201 Created
    Web-->>User: show receipt

PlantUML in two minutes

PlantUML is the other widely used text format. It has broader UML coverage (true use case, component and deployment diagrams) and runs on Java. The same animal example reads:

TEXT
@startuml
class Animal {
  +String name
  +eat()
}
class Dog {
  +bark()
}
Animal <|-- Dog
@enduml

The two languages look alike for class diagrams (<|-- is inheritance in both). If a team already standardizes on one, use it. In this track we use Mermaid so that diagrams render directly in the lesson.

Generating diagram text with code

Because diagrams are text, a script can write them. This is how reverse-engineering and documentation tools work: read some structure, emit diagram source.

Python Emit Mermaid class diagram text from data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Paste the printed text into any Mermaid renderer and you get the diagram. Scripts like this keep documentation honest because the diagram is regenerated from the same data the code uses.

Python Lint a diagram: every relationship must name known classes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A rendering engine will happily draw a box for Coupon, so a simple lint like this catches typos that a picture would hide. Text diagrams make that kind of automation possible.

Choosing a workflow

Pick a tool for the job

Whiteboard First sketch, group design talk.
Drawing tool One-off polished picture.
Diagram as code Lives with the repo.
Modeling suite Big, regulated projects.

Mix them. Sketch first, keep the useful ones as code.

1 / 2

Treat diagram source like code: commit it, review it, keep each diagram under about 15 elements, and give it a one-line caption that says what question it answers.

Practical advice

  • Keep notation honest. Mermaid will accept things UML forbids. When in doubt, check the meaning of a symbol in the notation lesson, not the tool's behavior.
  • Prefer small diagrams. Auto-layout becomes messy beyond a dozen or so elements.
  • Export for slides carefully. Export as SVG when you can; text stays sharp.
  • Name things in your domain language. Tools do not care, readers do.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main advantage of diagrams written as text?

    Text diagrams fit into version control and code review; validity is still your responsibility.
  2. 2. Which statement about Mermaid is true?

    Mermaid is a text-to-diagram library; it covers class, sequence, state, flowchart and others but not all UML types.
  3. 3. In Mermaid class diagrams, what does Animal <|-- Dog mean?

    <|-- is generalization: the arrowhead points at the parent.
  4. 4. When is a full modeling suite most justified?

    Suites add rigor and generation at the cost of weight and effort.

Summary

  • Tools range from whiteboards to full modeling suites; choose by the need.
  • Diagram-as-code (Mermaid, PlantUML) gives version control, reviews and automation.
  • Mermaid covers class, sequence, state and flow diagrams; other UML types are drawn with flowcharts here.
  • Scripts can generate or lint diagram text from data.
  • Tools do not enforce UML rules; you must know the notation.

Next: UML Notation Essentials