Mermaid vs. Diagramm-Canvas: Wann Diagrams as Code funktioniert und wann nicht

Kaum eine Tool-Debatte in Engineering-Teams dauert so lange an wie diese. Die einen wollen jedes Diagramm als Code, in Mermaid, im Pull Request reviewt. Die anderen wollen einen Canvas, auf dem sie Boxen verschieben und das System sehen können. Beide Lager haben recht, nur bei unterschiedlichen Diagrammen.

Dieser Guide vergleicht Mermaid und einen Diagramm-Canvas ehrlich: was beide gut können, wo sie an Grenzen stoßen, eine Entscheidungstabelle für typische Fälle und dasselbe kleine System, auf beide Arten gezeichnet.

Was Mermaid gut kann

Mermaid macht aus ein paar Zeilen Text ein Diagramm. Das hat echte Vorteile:

• Es lebt neben dem Code. Ein Diagramm in einer Markdown-Datei ändert sich im selben Pull Request wie der Code, den es beschreibt, und Reviewer sehen den Diff.
• Es wird dort gerendert, wo Entwickler ohnehin arbeiten. GitHub und GitLab rendern Mermaid-Codeblöcke in Markdown-Dateien, Issues und Pull Requests, und Tools wie Notion und Obsidian zeigen sie ebenfalls an.
• Kein zusätzliches Tool, kein Konto. Wer die Datei bearbeiten kann, kann auch das Diagramm bearbeiten.
• Sequenzdiagramme sind hervorragend. Für einen Request-Flow zwischen vier Services ist die Sequenz-Syntax von Mermaid kaum zu schlagen.
• KI-Assistenten schreiben Mermaid fließend. Bitte einen beliebigen Chat-Assistenten um ein Mermaid-Flussdiagramm, und du bekommst meistens gültige Syntax.

Wo Mermaid an Grenzen stößt

• Du kontrollierst das Layout nicht. Mermaid platziert Nodes automatisch. Füg eine einzige Kante hinzu, und das Bild kann sich neu anordnen; ab ein paar Dutzend Nodes wird es schwer lesbar.
• Text-Diffs verbergen visuelle Änderungen. Eine einzeilige Änderung im Pull Request kann das halbe Diagramm verschieben, und Reviewer sehen nur die Zeile.
• Das Vokabular für Infrastruktur ist dünn. Flussdiagramm-Formen sind generisch. Es gibt neuere Diagrammtypen für Architektur und C4, aber sie sind weniger ausgereift als Flussdiagramme und Sequenzdiagramme.
• Wer nicht entwickelt, bearbeitet es selten. Product Manager, Designer und Support-Teams können das Ergebnis lesen, ändern den Quelltext aber meist nicht.
• Keine gemeinsame Live-Session. Du bearbeitest Text in deinem Editor; es gibt keine Cursor, kein Live-Review und niemanden, der zusieht, wie eine Änderung ankommt.

Was ein Canvas gut kann

• Das Layout gehört dir. Die Position trägt Bedeutung: der Verlauf einer Vertrauensgrenze, der Weg eines Requests von links nach rechts, der Cluster in der Mitte.
• Typisierte Nodes und Frames. Auf einem Canvas wie Archboard ist ein Kubernetes-Service oder ein C4-Container ein Node mit Ports, und Namespaces oder VPCs sind Frames, die ihren Inhalt aufnehmen.
• Alle können bearbeiten. Auch wer das Repository nie öffnet, kann ein Label korrigieren oder eine Notiz ergänzen.
• Live-Zusammenarbeit und Teilen. Mehrere Personen und KI-Agenten bearbeiten gemeinsam mit Cursorn, und ein Live-Link oder eine Einbettung hält alle Lesenden auf dem aktuellen Stand.

Wo ein Canvas an Grenzen stößt

• Er driftet vom Code weg, wenn das Aktualisieren nicht Teil deines Workflows ist. Ein Canvas steckt standardmäßig nicht im Pull Request.
• Manche Formate sind undurchsichtig. Ein PNG oder eine proprietäre Datei lässt sich weder diffen noch generieren. Archboard mildert das mit JSON-Export und einem veröffentlichten JSON Schema, aber ein JSON-Dokument ist trotzdem kein zehnzeiliger Markdown-Block.
• Er braucht ein Tool. Lesende können einen Freigabelink ohne Konto ansehen, wer bearbeitet, braucht aber eins.

Eine Entscheidungstabelle

Das Muster: Mermaid gewinnt, wenn das Diagramm zu einer Änderung gehört und im Code lebt. Ein Canvas gewinnt, wenn das Diagramm dem Team gehört und jede einzelne Änderung überdauert.

Dasselbe System auf beide Arten

Hier ist ein kleines System in Mermaid:

flowchart LR
  user([Customer]) -->|HTTPS| web
  subgraph shop [Online shop]
    web[Web app] -->|JSON| api[Orders API]
    api -->|SQL| db[(Orders DB)]
    api -->|OrderPlaced| q[[order-events]]
    q --> worker[Email worker]
  end
  worker -->|SMTP| mail[Email provider]

Es ist lesbar, lässt sich gut diffen, und GitHub rendert es. Jetzt dasselbe Flussdiagramm auf einem Canvas. Wir haben es einem KI-Agenten gegeben, der über MCP mit Archboard verbunden ist, zusammen mit einer Zuordnung von Mermaid-IDs zu Node-Typen: user wird zur C4-Person, web, api und worker werden zu C4-Containern, db zu Postgres, q zu einem Thema (Topic) und mail zu einem externen System. Der Agent hat es in einem Schritt gezeichnet, ein zweiter Schritt hat es in zwei Reihen angeordnet:

Aus dem Subgraph wurde ein Frame, aus den Nodes wurden typisierte Nodes mit Ports, und das Ergebnis ist ein Ausgangspunkt, den du jetzt wie jedes andere Diagramm anordnen, annotieren und teilen kannst.

Bewusst beides nutzen

Eine Aufteilung, die für die meisten Teams funktioniert:

1. Mermaid für Diagramme, die zu einer Änderung gehören: Sequenzdiagramme in Design-Docs und Pull Requests, Zustandsautomaten neben dem Code, kleine Flussdiagramme in READMEs.
2. Ein Canvas für Diagramme, die dem Team gehören: Systemüberblicke, Infrastruktur, Security-Reviews, Onboarding.
3. Verbinde beides. Starte mit Mermaid, wenn du es schon hast: Ein Agent, der über MCP mit Archboard verbunden ist, kann ein Mermaid-Flussdiagramm in ein Canvas-Diagramm mit echten Node-Typen verwandeln. Exportiere den Canvas als JSON ins Repository, wenn er mit dem Code reviewt werden soll, und verlinke das Live-Diagramm im README.

FAQ

Kann ich Mermaid in den Archboard-Editor einfügen? Heute noch nicht direkt. Ein über MCP verbundener KI-Agent kann ein Mermaid-Flussdiagramm samt Subgraphs als Canvas-Diagramm mit echten Node-Typen zeichnen. Andere Mermaid-Diagrammarten wie Sequenzdiagramme werden nicht konvertiert.

Taucht ein Canvas-Diagramm in Pull Requests auf? Nicht von selbst. Exportiere es als JSON oder SVG ins Repository, wenn es mit dem Code reviewt werden soll, oder verlinke das Live-Diagramm im Pull Request.

Ist Diagrams as Code immer aktueller? Nur wenn jemand es aktualisiert. Ein Mermaid-Block, den niemand anfasst, veraltet genauso schnell wie ein Canvas; der Unterschied ist, dass er näher an der Änderung liegt, die ihn aktualisieren sollte.

Was ist mit PlantUML oder Structurizr? Dieselben Trade-offs. PlantUML ist stark bei UML- und Sequenzdiagrammen, Structurizr ist für C4-Modelle als Code gebaut. Entscheide danach, wer das Diagramm bearbeitet und wie lange es leben muss.

Womit kommen KI-Assistenten besser zurecht? Mit beidem. Assistenten schreiben Mermaid fließend, und über MCP kann ein Agent auch direkt einen Canvas bearbeiten, wo Menschen die Änderung live sehen und sie rückgängig machen können.

Kostenlos starten — ein Seat, keine Kreditkarte.