Backstage vs Archyl: Zwei Ansätze zur Architekturdokumentation

Wenn Sie Werkzeuge für die Architekturdokumentation evaluieren, haben Sie wahrscheinlich Backstage angeschaut. Es ist Open-Source, wird von Spotify unterstützt, und hat ein Plugin-Ökosystem, das alles von CI/CD bis Kostenmanagement abdeckt. Eines dieser Plugins behandelt C4-Diagramme.

Archyl nimmt den entgegengesetzten Ansatz. Es ist kein Entwicklerportal. Es verwaltet keine CI-Pipelines oder Service-Kataloge. Es macht eine Sache: Architekturdokumentation mit dem C4-Modell — und geht dabei in die Tiefe.

Dieser Artikel ist kein „welches Tool ist besser". Sie dienen unterschiedlichen Zwecken. Aber wenn das, was Sie tatsächlich brauchen, Architekturdokumentation ist, dann sind die Unterschiede wichtig. Lassen Sie mich sie durchgehen.

Die Kernphilosophie

Backstage ist ein Framework für Entwicklerportale. Seine Aufgabe ist es, alle Werkzeuge, Services und Dokumentation, die ein Entwicklungsteam nutzt, in einer einzigen internen Plattform zu vereinen. Architekturdokumentation ist eines von vielen verfügbaren Plugins — eine Funktion innerhalb eines größeren Ökosystems.

Archyl ist eine zweckgebundene Architekturdokumentationsplattform. Das gesamte Produkt existiert, um Softwarearchitektur mit dem C4-Modell zu modellieren, zu visualisieren, zu analysieren und weiterzuentwickeln. Jede Funktion dient diesem einen Zweck.

Dieser Unterschied im Umfang prägt alles andere.

C4-Modell-Unterstützung

Backstage

Das Entitätsmodell von Backstage umfasst Components, APIs, Resources, Systems, Domains, Groups und Users. Das entspricht ungefähr den C4-Ebenen 1 und 2 — Systeme und Container. Aber die Zuordnung ist annähernd, nicht präzise.

Das C4-Plugin für Backstage (backstage-plugin-c4-model) rendert Diagramme aus den vorhandenen Katalog-Entitäten. Es unterstützt System-Kontext- und Container-Ansichten. Es gibt keine native Unterstützung für C4-Ebene 3 (Komponenten) oder Ebene 4 (Code). Wenn Ihre Architekturmodellierung unter die Container-Ebene gehen muss, stoßen Sie an eine Grenze.

Der Katalog selbst ist YAML-gesteuert. Jede Entität wird in catalog-info.yaml-Dateien definiert, die typischerweise neben dem Code committed werden. Das bedeutet, Architektur wird in Konfigurationsdateien definiert, nicht in einem visuellen Werkzeug.

Archyl

Archyl implementiert alle vier C4-Ebenen nativ:

• Ebene 1 — Systemkontext: Systeme, externe Systeme und Personen
• Ebene 2 — Container: Anwendungen, Services, Datenbanken, Message Queues, Caches und mehr
• Ebene 3 — Komponente: Controller, Services, Repositories, Handler, Middleware, Modelle
• Ebene 4 — Code: Klassen, Interfaces, Funktionen, Methoden, Enums, Konstanten

Jede Ebene hat eigene Knotentypen, visuelle Stile und Metadaten. Sie können von einem System in seine Container eintauchen, von einem Container in seine Komponenten, von einer Komponente in ihre Code-Elemente — alles innerhalb desselben interaktiven Diagramms. Beziehungen zwischen Elementen auf jeder Ebene sind erstklassige Bürger mit typisierten Verbindungen (uses, depends_on, calls, reads_from, writes_to, etc.).

Der Unterschied: Backstage gibt Ihnen einen Katalog mit aufgesetzten C4-Ansichten. Archyl gibt Ihnen eine vollständige C4-Modellierungsumgebung, in der Sie Ihre gesamte Architektur auf jedem Detailgrad darstellen können.

Visualisierung

Backstage

Das C4-Plugin erzeugt statische oder semi-interaktive Diagramme aus den Katalogdaten. Die Visualisierung hängt von der spezifischen Plugin-Implementierung ab — einige nutzen PlantUML, einige Structurizr, einige rendern im Browser. Aber die Erfahrung ist grundsätzlich schreibgeschützt. Sie betrachten Diagramme, die aus YAML-Definitionen generiert wurden. Sie interagieren nicht mit ihnen.

Es gibt keine Canvas-Manipulation, kein Drag-and-Drop-Positionieren, keine Echtzeit-Kollaboration an Diagrammen. Um die Architekturdarstellung zu ändern, bearbeiten Sie YAML-Dateien und warten, bis sich der Katalog aktualisiert.

Archyl

Archyl bietet einen vollständig interaktiven Canvas auf Basis von React Flow. Sie können:

• Jedes Element auf dem Diagramm ziehen und positionieren
• Beziehungen zwischen Elementen direkt auf dem Canvas zeichnen
• Zwischen C4-Ebenen navigieren, indem Sie in Systeme, Container und Komponenten eintauchen
• Echtzeit-Cursor von Teammitgliedern sehen, die am selben Diagramm arbeiten
• Auto-Layout nutzen, um Elemente automatisch anzuordnen, oder sie manuell positionieren
• Overlays anwenden, um verwandte Elemente visuell zu gruppieren
• Zwischen hellem und dunklem Theme auf dem Diagramm wechseln

Der Canvas ist der primäre Arbeitsbereich, kein generiertes Artefakt. Jede Änderung, die Sie am Diagramm vornehmen, wird sofort reflektiert.

KI-gestützte Entdeckung

Backstage

Backstage hat keine eingebaute KI-gestützte Architekturerkennung. Um den Katalog zu füllen, erstellen Sie manuell catalog-info.yaml-Dateien für jeden Service oder nutzen Entity-Provider, die aus externen Quellen importieren (Kubernetes, GitHub, etc.). Einige Community-Plugins fügen KI-Fähigkeiten hinzu, aber es gibt keine native Architekturanalyse aus dem Code.

Wenn Sie 200 Services haben und keiner hat catalog-info.yaml-Dateien, schreiben Sie 200 YAML-Dateien von Hand — oder bauen benutzerdefinierte Tools, um sie zu generieren.

Archyl

Archyl enthält eine eingebaute KI-Entdeckung, die sich mit Ihrem Git-Repository verbindet (GitHub, GitLab, Bitbucket, Azure DevOps, Gitea oder lokale Repos), Ihren Quellcode liest und automatisch ein vollständiges C4-Modell generiert.

Die Entdeckungs-Pipeline:

1. Verbindet sich mit Ihrem Repository
2. Analysiert Quelldateien, Infrastruktur-Code und Konfiguration
3. Identifiziert Systeme, Container, Komponenten und ihre Beziehungen
4. Erkennt Abhängigkeiten aus Paket-Manifesten
5. Generiert ein vorgeschlagenes C4-Modell mit Auto-Layout
6. Präsentiert das Ergebnis zur Überprüfung und Genehmigung

Sie können jeden Teil des generierten Modells genehmigen, modifizieren oder ablehnen. Die KI übernimmt die schwere Arbeit der initialen Architekturkartierung; Sie liefern das Urteilsvermögen.

Das System versteht Go, TypeScript, JavaScript, Python, Java, Kotlin, Swift, Rust, C/C++, Ruby, Scala, Terraform, Docker, Kubernetes YAML, Helm Charts und mehr.

Architecture Decision Records

Backstage

ADRs in Backstage werden typischerweise über das ADR-Plugin gehandhabt, das ADR-Markdown-Dateien aus einem Repository liest. Es zeigt sie in der Backstage-Oberfläche an, oft im MADR-Format (Markdown Architectural Decision Records). Die ADRs leben in Git als Markdown-Dateien.

Es gibt keine Verknüpfung zwischen ADRs und Katalog-Entitäten. Ein ADR über die Wahl von PostgreSQL statt MongoDB liegt in einem /docs/adr/-Ordner — es gibt keine direkte Verbindung zum Datenbank-Container, auf den er sich bezieht.

Archyl

ADRs in Archyl sind erstklassige Objekte, die direkt mit C4-Elementen verknüpft sind. Wenn Sie einen ADR erstellen, können Sie ihn an bestimmte Systeme, Container, Komponenten oder Code-Elemente anhängen. Das bedeutet:

• Öffnen Sie einen Container im Diagramm und sehen seine zugehörigen ADRs
• Durchsuchen Sie ADRs und sehen genau, welche Architekturelemente sie betreffen
• Verstehen Sie die Begründung hinter architektonischen Entscheidungen im Kontext

ADRs unterstützen Status (vorgeschlagen, akzeptiert, veraltet, ersetzt) und reichhaltigen Markdown-Inhalt mit strukturierten Abschnitten für Kontext, Entscheidung und Konsequenzen.

Dokumentation

Backstage

Das TechDocs-System von Backstage konvertiert Markdown-Dateien (typischerweise über MkDocs) in durchsuchbare Dokumentation innerhalb des Portals. Es ist Markdown-basiert und Git-gestützt. Die Dokumentation wird gut gerendert und unterstützt Suche.

Allerdings ist TechDocs Allzweck-Dokumentation, keine Architekturdokumentation. Es gibt keine strukturelle Verbindung zwischen Docs und dem Architekturmodell. Eine Seite über „Authentifizierungsarchitektur" verlinkt nicht auf das Authentifizierungssystem im Diagramm.

Archyl

Archyls Dokumentationssystem ist mit dem Architekturmodell integriert. Dokumentationselemente können mit C4-Elementen verknüpft, in Ordnern organisiert und im Kontext neben den Diagrammen aufgerufen werden. Wenn Sie ein System oder einen Container betrachten, ist seine zugehörige Dokumentation im Seitenpanel sichtbar.

Es geht nicht darum, allgemeine Dokumentationstools zu ersetzen. Es geht darum sicherzustellen, dass Architekturdokumentation neben der Architektur lebt, die sie beschreibt.

Impact-Analyse

Backstage

Backstage hat keine Impact-Analyse-Fähigkeit. Wenn Sie verstehen wollen, was kaputtgeht, wenn Sie einen Service deprecaten, verfolgen Sie Abhängigkeiten manuell durch den Katalog. Es gibt keine automatisierte Upstream-/Downstream-Analyse, keinen Risiko-Score, keine Was-Wäre-Wenn-Simulation.

Manche Organisationen bauen eigene Skripte oder Plugins, um Katalogbeziehungen zu analysieren, aber es gibt nichts Eingebautes.

Archyl

Archyls Impact Radar bietet umfassende Impact-Analyse direkt auf dem Diagramm. Rechtsklicken Sie auf ein beliebiges Element und sehen Sie sofort:

• Upstream-Abhängige und Downstream-Abhängigkeiten organisiert nach Grad (1, 2, 3 Sprünge)
• Risiko-Score berechnet aus Upstream-Abhängigen, Downstream-Reichweite, strukturellen Kindern und Kopplungsgrad
• Kritischer Pfad, der die längste Abhängigkeitskette hervorhebt
• Projektübergreifende Abhängigkeiten bei Nutzung der Globalen Architektur
• Betroffene Flows abgeglichen mit dokumentierten Benutzerreisen
• Was-Wäre-Wenn-Simulation, die genau zeigt, was kaputtgeht, wenn ein Element entfernt wird

Die Analyse läuft deterministisch über den Beziehungsgraphen. Keine Vermutungen, keine Meetings, um herauszufinden, wer betroffen ist.

Änderungsmanagement

Backstage

Änderungen am Backstage-Katalog gehen über Git. Sie erstellen einen PR, der catalog-info.yaml modifiziert, lassen ihn reviewen und mergen. Das ist der Standard-Git-Workflow — es gibt kein architekturspezifisches Änderungsmanagement.

Das Review findet in GitHub/GitLab statt, nicht im Kontext der Architektur. Reviewer sehen YAML-Diffs, keine visuellen Diffs, wie sich die Architektur ändert.

Archyl

Archyl hat dedizierte Architecture Change Requests — einen Pull-Request-ähnlichen Workflow speziell für Architekturänderungen. Sie schlagen Änderungen am C4-Modell vor, Reviewer sehen genau, was hinzugefügt, geändert oder entfernt wird, und die Änderung durchläuft einen Genehmigungsprozess, bevor sie angewendet wird.

Das bringt Governance in die Architekturevolution, ohne alles durch YAML-Dateien und Git-Diffs zu zwingen.

Zusammenarbeit

Backstage

Backstage ist ein Webportal. Mehrere Personen können gleichzeitig darauf zugreifen, aber es gibt keine Echtzeit-Kollaboration an der Architektur selbst. Sie betrachten den Katalog unabhängig voneinander. Es gibt keine Live-Cursor, keine Präsenzanzeigen, keine gleichzeitige Bearbeitung.

Archyl

Archyl bietet Echtzeit-Kollaboration an C4-Diagrammen:

• Live-Cursor, die zeigen, wo Teammitglieder sich auf dem Canvas befinden
• Präsenzanzeigen, die zeigen, wer das Diagramm betrachtet
• Element-Fokus-Tracking, damit Sie sehen, welche Elemente Teammitglieder bearbeiten
• Gleichzeitige Bearbeitung mit Konfliktlösung

Das erstreckt sich sowohl auf C4-Diagramme auf Projektebene als auch auf die Globale Architektur-Ansicht.

Operative Echtzeitdaten

Eine der größten Überraschungen bei der Entdeckung von Archyl ist der Marketplace. Architekturdokumentation besteht nicht nur aus statischen Diagrammen — Archyl verbindet sich mit den Werkzeugen, die Ihre Teams bereits nutzen, und zeigt Live-Daten direkt auf Ihrer Architektur an.

Backstage

Das Plugin-Ökosystem von Backstage ist hier seine größte Stärke. Es gibt Plugins für fast alles — CI/CD-Status, Monitoring-Dashboards, Kostenverfolgung, Kubernetes-Status und mehr. Aber diese Plugins leben auf eigenen Seiten innerhalb des Portals. Sie sind nicht mit der Architekturansicht verbunden. Sie sehen den CI/CD-Status eines Services auf seiner Katalogseite, aber nicht auf dem C4-Diagramm, wo dieser Service im Kontext mit allem lebt, wovon er abhängt.

Archyl

Der Marketplace von Archyl bietet Integrationen, die Live-Daten als Widgets direkt auf Ihren Architektur-Dashboards anzeigen:

• CI/CD: GitHub Actions Workflow-Status, offene PRs, Dependabot-Alerts, Security-Scanning. GitLab Pipeline-Status, Merge Requests, Vulnerability-Berichte, SAST/DAST-Alerts. Argo CD Anwendungsstatus und Deployment-Tracking.
• Observability: Eingebettete Datadog-Dashboards, Metrik-Abfragen, Monitor-Status. Prometheus Instant- und Range-Queries, Target-Health. Sentry Error-Tracking.
• Code-Qualität: SonarQube Quality-Gate-Status, Code-Metriken, Issues, Security-Hotspots und Bewertungen.
• Incident-Management: PagerDuty Incident-Status, aktive Incidents, Bereitschaftspläne, Service-Health.

Widgets aktualisieren sich automatisch und können auf drei Ebenen eingerichtet werden — organisationsweit, pro Projekt oder an ein bestimmtes C4-Element angehängt. Ein Container, der Ihren Zahlungsservice darstellt, kann seinen GitHub Actions Build-Status, sein SonarQube Quality Gate, seine Datadog Health-Metriken und seinen PagerDuty Bereitschaftsplan anzeigen — alles an einem Ort.

Das verwandelt Architekturdokumentation von einer statischen Referenz in eine lebendige operative Ansicht. Das Diagramm zeigt nicht nur, wie Ihr System aussieht — es zeigt, wie es ihm gerade geht.

Über die Grundlagen hinaus

Einige weitere Bereiche, in denen sich die Ansätze unterscheiden:

Wann was wählen

Wählen Sie Backstage, wenn Sie ein einheitliches Entwicklerportal benötigen, das Dokumentation, CI/CD, Service-Katalog, Kostenmanagement und Dutzende anderer Anliegen in einer einzigen internen Plattform zusammenfasst. Architekturdokumentation ist ein Teil dieses Puzzles, und eine High-Level-C4-Ansicht reicht für Ihre Bedürfnisse.

Wählen Sie Archyl, wenn Architekturdokumentation ein primäres Anliegen ist — Sie aber nicht auf operative Sichtbarkeit verzichten wollen. Archyl geht in die Tiefe beim C4-Modell (alle 4 Ebenen), interaktiven Diagrammen, KI-gestützter Entdeckung, Impact-Analyse und Änderungs-Governance, während seine Marketplace-Integrationen Live-CI/CD-Status, Monitoring, Code-Qualität und Incident-Daten direkt auf Ihre Architektur bringen. Sie erhalten fokussierte Architektur-Tools ohne den operativen Kontext zu verlieren, den Backstage über sein Plugin-Ökosystem bereitstellt.

Sie können auch koexistieren. Archyl übernimmt die detaillierte Architekturmodellierung, -analyse und operative Sichtbarkeit im Kontext Ihrer Architektur. Backstage übernimmt die breitere Entwicklererfahrung — Onboarding, Katalogsuche, Kosten-Dashboards und allgemeine Dokumentation. Das Architekturmodell in Archyl kann informieren, was Sie im Service-Katalog von Backstage dokumentieren, ohne dass eines das andere ersetzt.

Das Fazit

Backstage ist ein Plattform-Framework, das Sie aus Plugins zusammensetzen. Es ist leistungsstark, flexibel und löst das Problem der Fragmentierung der Entwicklererfahrung. Aber seine Architekturdokumentationsfähigkeiten beschränken sich auf das, was kataloggesteuerte C4-Plugins bieten können — typischerweise Ebenen 1 und 2, statische Ansichten, keine KI, keine Impact-Analyse, keine Echtzeit-Kollaboration an Diagrammen.

Archyl ist ein fokussiertes Werkzeug, das bei der Architektur in die Tiefe geht. Es deckt das vollständige C4-Modell, KI-Entdeckung, Impact-Analyse, Änderungs-Governance, Echtzeit-Kollaboration ab — und verbindet sich mit Ihren CI/CD-, Observability-, Code-Qualitäts- und Incident-Management-Tools, damit Ihre Architektur in der operativen Realität verankert bleibt. Es ist kein Entwicklerportal, aber es ist weit mehr als statische Dokumentation.

Ihre Architektur verdient mehr als einen Katalogeintrag.

Neu beim C4-Modell? Starten Sie mit unserer Einführung in das C4-Modell. Modellieren Sie bereits? Probieren Sie die KI-gestützte Architekturerkennung, um Ihr erstes Projekt aus dem Code zu starten, oder erkunden Sie Impact Radar, um Veränderungen zu verstehen, bevor Sie sie umsetzen.