This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Diagrams-as-Code

1 - Mermaid

Introduction

Mermaid is a JavaScript-based diagramming and visualization library that enables the creation of diagrams and flowcharts using text descriptions. Mermaid is frequently used in Markdown documents (e.g., in GitHub, GitLab, or Confluence) to visually represent complex relationships.

Advantages of Mermaid:

  • Simple integration into Markdown documents.
  • No external tools required – diagrams are rendered directly in the browser.
  • Supports a wide variety of diagram types.
  • Ideal for documentation, presentations, and technical specifications.

Possible Diagrams

Flowchart

Flowcharts visualize processes or workflows. They consist of nodes (steps) and connections (arrows) representing the sequence of steps.

Example:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process 1]
    B -->|No| D[Process 2]
    C --> E[End]
    D --> E

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process 1]
    B -->|No| D[Process 2]
    C --> E[End]
    D --> E

Explanation:

  • flowchart TD: Defines a flowchart from top to bottom.
  • A[Start]: A node labeled “Start”.
  • -->: Connection between nodes.
  • |Yes| and |No|: Labels for the connections.

Class Diagram

Class diagrams show the structure of classes, their attributes, methods, and relationships to each other.

Example:

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

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

Explanation:

  • classDiagram: Defines a class diagram.
  • Animal and Dog: Classes with attributes (-name) and methods (+eat()).
  • <|--: Inheritance relationship (Dog inherits from Animal).

Sequence Diagram

Sequence diagrams visualize interactions between objects or actors in a chronological sequence.

Example:

sequenceDiagram
    Alice->>Bob: Hello!
    Bob-->>Alice: Hello back!

sequenceDiagram
    Alice->>Bob: Hello!
    Bob-->>Alice: Hello back!

Explanation:

  • sequenceDiagram: Defines a sequence diagram.
  • Alice->>Bob: Message from Alice to Bob.
  • -->>: Response from Bob to Alice.

Entity-Relationship Diagram (ER Diagram)

ER diagrams show the relationships between entities in a database.

Example:

erDiagram
    CUSTOMER ||--o{ ORDER : has
    CUSTOMER {
        int id PK
        string name
    }
    ORDER {
        int id PK
        date orderDate
    }

erDiagram
    CUSTOMER ||--o{ ORDER : has
    CUSTOMER {
        int id PK
        string name
    }
    ORDER {
        int id PK
        date orderDate
    }

Explanation:

  • erDiagram: Defines an ER diagram.
  • CUSTOMER ||--o{ ORDER: One customer has many orders.
  • PK: Primary key.

State Diagram

State diagrams show the states of a system and the transitions between these states.

Example:

stateDiagram-v2
    state s1
    state Off
    state On
    
    [*] --> Off
    Off --> On: Turn On
    On --> Off: Turn Off

stateDiagram-v2
    state s1
    state Off
    state On
    
    [*] --> Off
    Off --> On: Turn On
    On --> Off: Turn Off

Explanation:

  • stateDiagram-v2: Defines a state diagram.
  • [*]: Start state.
  • Off --> On: Transition from “Off” to “On” via “Turn On”.

Mindmap Diagram

Mindmaps visualize hierarchical ideas or concepts.

Example:

mindmap
  root((Topic))
    Branch 1
      Subtopic 1
      Subtopic 2
    Branch 2
      Subtopic 3

mindmap
  root((Topic))
    Branch 1
      Subtopic 1
      Subtopic 2
    Branch 2
      Subtopic 3

Explanation:

  • mindmap: Defines a mindmap.
  • root((Topic)): Central topic.
  • Indentations define the hierarchy.

Requirement Diagram

Requirement diagrams show requirements and their relationships.

Example:

requirementDiagram
  requirement Requirement1 {
    id: 1
    text: "The system must be secure."
  }

  element System {
    type: software
  }

  System - satisfies -> Requirement1

requirementDiagram
  requirement Requirement1 {
    id: 1
    text: "The system must be secure."
  }

  element System {
    type: software
  }

  System - satisfies -> Requirement1

Explanation:

  • requirementDiagram: Defines a requirement diagram.
  • requirement: Defines a requirement.
  • satisfies: Relationship between element and requirement.

Gantt Diagram

Gantt diagrams visualize project plans and timelines.

Example:

gantt
    title Project Plan
    dateFormat YYYY-MM-DD
    section Phase 1
    Task 1 :a1, 2024-01-01, 7d
    Task 2 :after a1, 3d

gantt
    title Project Plan
    dateFormat YYYY-MM-DD
    section Phase 1
    Task 1 :a1, 2024-01-01, 7d
    Task 2 :after a1, 3d

Explanation:

  • gantt: Defines a Gantt diagram.
  • dateFormat: Format for date specifications.
  • Task 1 :a1, 2024-01-01, 7d: Task 1 lasts 7 days starting from January 1, 2024.

Timeline

Timelines show events in chronological order.

Example:

timeline
    title Important Events 2024 - 2025
    2024 : Event 1
    2025 : Event 2

timeline
    title Important Events 2024 - 2025
    2024 : Event 1
    2025 : Event 2

Explanation:

  • timeline: Defines a timeline.
  • 2024 : Event 1: Event in the year 2024.

Further Information

Mermaid Open-Source

2 - PlantUML

Introduction

PlantUML is an open-source tool that enables the generation of diagrams from simple text descriptions. It supports a wide variety of diagram types, both UML-based and non-UML-based. PlantUML is particularly useful for developers, architects, and project managers, as it simplifies the creation and maintenance of diagrams and can be integrated into many development environments.

Possible UML-based Diagrams

Sequence Diagram

Description: A sequence diagram shows the interaction between objects in a specific order. It is frequently used to visualize the flow of messages between objects in a system.

Example in PlantUML:

@startuml 
Alice -> Bob: Hello! 
Bob --> Alice: Hello back! 
@enduml

Sequence Diagram

Explanation:

  • -> shows a message from one object to another.
  • --> shows a response.

Activity Diagrams

Description: Activity diagrams (also known as flowcharts) show the flow of activities and decisions in a process. They are particularly useful for visualizing business processes or algorithms.

Example in PlantUML:

@startuml 
start
 :Activity 1; :Activity 2; 
if (Condition?) then (Yes)
 :Activity 3; 
 else (No)
 :Activity 4; 
 endif 
 stop 
@enduml

Activity Diagram

Explanation:

  • start and stop mark the beginning and end of the process.
  • if and else show decisions.

Class Diagram

Description: Class diagrams show the structure of a system through classes, their attributes, methods, and the relationships between the classes.

Example in PlantUML:

@startuml 
class  Car {   
            -brand: String 
            -model: String +drive() 
            }   
class  Driver {   
            -name: String +steer() 
            }   
Car "1" *-- "1" Driver 
@enduml

Class Diagram

Explanation:

  • - shows private attributes, + shows public methods.
  • --> shows an association between classes.

Object Diagram

Description: Object diagrams show instances of classes at a specific point in time and their relationships to each other.

Example in PlantUML:

@startuml 
object Car1 {
            brand = "VW" 
            model = "Golf" 
            }   
object Driver1 {
            name = "Max" 
            }   
Car1 --> Driver1 
@enduml

Object Diagram

Explanation:

  • object defines an instance of a class.
  • --> shows a relationship between objects.

State Diagram

Description: State diagrams show the various states of an object and the transitions between these states.

Example in PlantUML:

@startuml 
[*] --> Off 
Off --> On : switch on 
On --> Off : switch off 
@enduml

State Diagram

Explanation:

  • [*] shows the start state.
  • --> shows a transition between states.

Possible Non-UML-based Diagrams

Visualization of JSON/YAML Data

Description: PlantUML can visualize JSON or YAML data to better understand the structure and hierarchy of the data.

Example in PlantUML:

@startjson 
{
 "name": "Max", 
 "age": 30, 
 "address": { 
            "street": "Main Street 1", 
            "city": "Berlin" 
            } 
} 
@endjson

JSON/YAML

Explanation:

  • @startjson and @endjson enclose the JSON code.

Archimate Diagram

Description: Archimate diagrams are used to model enterprise architectures. They show the relationships between business processes, applications, and technologies.

Example in PlantUML:

@startuml 
archimate #Business "Business Process" as bp 
archimate #Application "Application" as app 
bp --> app 
@enduml

Archimate Diagram

Explanation:

  • archimate defines an Archimate element.
  • --> shows a relationship between elements.

Gantt Diagram

Description: Gantt diagrams show project plans and the timeline of tasks.

Example in PlantUML:

@startgantt 
[Task 1] lasts 5 days 
[Task 2] starts at [Task 1]'s end and lasts 3 days 
@endgantt

Gantt Diagram

Explanation:

  • lasts defines the duration of a task.
  • starts at shows the start of a task relative to another.

Mindmap Diagram

Description: Mindmaps visualize ideas and concepts in a hierarchical structure.

Example in PlantUML:

@startmindmap 
* Root 
** Branch 1 
*** Leaf 1 
** Branch 2 
@endmindmap

Mindmap

Explanation:

  • * shows the root node.
  • ** and *** show child nodes.

Network Diagram

Description: Network diagrams show the structure and connections in a network.

Example in PlantUML:

@startuml 
node "Server" as s 
node "Client" as c 
s -- c 
@enduml

Network Diagram

Explanation:

  • node defines a node in the network.
  • -- shows a connection between nodes.

Work Breakdown Structure (WBS)

Description: A Work Breakdown Structure (WBS) shows the hierarchy and structure of a project.

Example in PlantUML:

@startwbs 
* Project 
** Phase 1 
*** Task 1 
*** Task 2 
** Phase 2 
@endwbs

Work Breakdown Structure

Explanation:

  • * shows the main project.
  • ** and *** show sub-elements.

Further Information