Verwandeln Sie Ihren Backstage-Katalog in 60 Sekunden in eine echte C4-Architektur

Backstage ist der Katalog. Wenn Sie in einem Plattform-Team arbeiten, haben Sie wahrscheinlich Monate damit verbracht, catalog-info.yaml-Dateien zu pflegen, Annotationen einzurichten, dependsOn-Verknüpfungen zu korrigieren und Slack-Fragen zu beantworten, warum ein Service nicht angezeigt wird. Diese Arbeit ist real. Sie repräsentiert eine echte Karte Ihrer Systeme.

Aber hier ist die Sache: Backstage wurde gebaut, um Ihre Software zu listen, nicht um sie zu modellieren. Die Component-Seiten sind nützlich. Die Beziehungen sind spärlich. Das C4-Plugin ist eine nachträgliche Ergänzung. Sie können durch 700 Services in einer flachen Liste scrollen, aber Sie können nicht sehen, wie sie zusammenpassen.

Wenn Sie eine echte Architektur-Sicht wollten, hatten Sie meistens eine Wahl: Bauen Sie Ihren Katalog manuell in einem anderen Tool neu auf, oder leben Sie mit dem, was Backstage bietet.

Heute fällt diese Wahl weg.

Archyl importiert jetzt Ihren Backstage Software Catalog direkt. Ein curl, ein Upload, und jedes System, jede Component, jede Resource und jede API, die Sie bereits gepflegt haben, erscheint als vollständiges, navigierbares C4-Modell — mit Beziehungen, OpenAPI-Verträgen, Infrastruktur-Ressourcen und Metadaten intakt.

Sechzig Sekunden, drei Schritte

Backstage exponiert seinen vollständigen Entitätskatalog über einen einzigen REST-Endpoint. Holen Sie ihn, legen Sie ihn in Archyl ab, fertig.

Schritt 1 — Exportieren Sie Ihren Katalog

curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
  https://backstage.your-company.com/api/catalog/entities \
  -o entities.json

Das ist der gesamte Export. Der Endpoint streamt jede Entität, die Backstage kennt: Systems, Components, Resources, APIs, Groups, Users — alles. Für die meisten Organisationen erhalten Sie ein 5–30 MB JSON-Array mit Tausenden von Einträgen.

Wenn Sie ohne Auth testen (einige Backstage-Instanzen erlauben öffentliche Katalog-Lesezugriffe im internen Netzwerk), können Sie den Authorization-Header weglassen. Wenn Sie nach Kind filtern müssen, um die Datei kleiner zu halten, unterstützt Backstage Query-Parameter: ?filter=kind=component,kind=system,kind=api,kind=resource reduziert die Antwort auf das, was Archyl tatsächlich abbildet.

Schritt 2 — Öffnen Sie den Import-Dialog

Klicken Sie in Archyl auf Projekt importieren (oder Importieren in einem bestehenden Projekt), wählen Sie den Backstage-Tab und laden Sie entweder entities.json hoch oder fügen Sie es direkt ein.

Archyl validiert die Datei und zeigt Ihnen dann genau, was erstellt wird — Anzahl Systeme, Container, API-Verträge, Beziehungen — bevor irgendetwas geschrieben wird.

Schritt 3 — Klicken Sie auf Importieren

Ihr Projekt ist befüllt. Ein 9 MB Katalog mit ~3.000 Entitäten importiert in Sekunden. Sie können nun in jedes System klicken, dessen Container im C4 Level 2 sehen, in APIs einsteigen und dependsOn-Kanten durch Ihren Stack verfolgen.

Was tatsächlich abgebildet wird

Der schwierige Teil beim Import aus Backstage ist nicht das Lesen des JSON — es ist das Übersetzen zwischen zwei verschiedenen Denkmodellen. Backstage denkt in flachen Entitäten, die durch typisierte Relationen verbunden sind. C4 denkt in verschachtelten Ebenen. So überbrückt Archyl die beiden:

Backstage Archyl Hinweise
System C4 System (Ebene 1) Systeme mit gleichem Namen über Namespaces hinweg werden automatisch eindeutig gemacht
Component Container unter dem zugehörigen System service → service, cronworkflow → worker, website → web_app
Resource Container unter dem zugehörigen System Typ-bewusst: s3-bucket → file_storage; rds-instance, dynamo-db-table, valkey-cluster, opensearch-domain → database; kafka-topic, sqs-queue → message_queue; repository → library
API (mit spec.definition) API-Vertrag OpenAPI 3, gRPC, GraphQL, AsyncAPI-Spezifikationen werden inline erhalten und mit Provider-/Consumer-Components verknüpft
dependsOn, dependencyOf Beziehung depends_on Bidirektionale Paare werden automatisch dedupliziert
consumesApi Beziehung uses Aufgelöst über die API zum tatsächlichen Provider-Component
producesTo, producedBy Beziehung publishes_to
consumesFrom, consumedBy Beziehung consumes_from
versionedIn, versions Beziehung depends_on Mit „source code" beschriftet
metadata.namespace, spec.lifecycle, spec.type, metadata.tags Tags Alle übernommen für Filterung und Overlays
User, Group Übersprungen Der People-Graph ist kein C4-Konzept

Components und Resources ohne spec.system landen in einem synthetischen System namens Uncategorized, sodass nichts stillschweigend verworfen wird.

Die zwei Details, die in der Praxis am meisten zählen:

  • API-Verträge kommen mit ihrem Inhalt. Jede Backstage-API-Entität, die eine spec.definition enthält (Ihr inline OpenAPI YAML, Ihr gRPC .proto), wird als Archyl API-Vertrag importiert, mit der vollständigen Spec angehängt und mit dem Provider-Component verknüpft. Kein erneutes Hochladen von Specs von Hand.
  • Resource-Typen bleiben erhalten. Ein Kafka-Topic wird kein generischer „service" — es ist ein message_queue-Container. Eine RDS-Instanz ist eine database. Ein S3-Bucket ist file_storage. Ihr visuelles Modell spiegelt die tatsächliche Natur jedes Infrastrukturteils wider.

Ein Wort zur Resource-Flut

Wenn Ihre Organisation stark auf Kubernetes läuft, hat Ihr Backstage-Katalog wahrscheinlich Hunderte — vielleicht Tausende — von external-secret, repository, datadog-service- und load-balancer-Resources, die automatisch aus Clustern entdeckt werden. Wir importieren sie alle.

Das mag auf den ersten Blick viel aussehen. Ist es auch.

Aber Sie haben mehrere Optionen:

  • Behalten und filtern. Jeder importierte Container trägt einen Tag wie type:external-secret (oder ähnlich). Archyls Overlays und Tag-Filter erlauben Ihnen, sie im Diagramm auszublenden, während sie abfragbar bleiben.
  • Massenlöschung von Rauschen. Zwei Klicks pro Typ, um eine ganze Kategorie zu entfernen, wenn Sie sie nicht in Ihrem Modell wollen.
  • Mit Filter neu exportieren. Verwenden Sie Backstages ?filter=-Query-Parameter, um Resource-Kinds, die Sie nicht interessieren, vor dem Import auszuschließen.

Wir haben uns entschieden, alles zu importieren, weil die Alternative — stillschweigendes Verwerfen von Daten, die wir für unwichtig hielten — schlechter ist. Sie haben Ihren Katalog gepflegt. Sie entscheiden, was bleibt.

Was Sie wirklich gewinnen

Ein Backstage-Katalog sagt Ihnen, was existiert. Eine Archyl-Architektur sagt Ihnen, was passiert.

Sobald Ihr Katalog in Archyl lebt, schalten Sie Dinge frei, die Backstage einfach nicht macht:

Ein echtes C4-Diagramm. Interaktiv, zoombar, navigierbar über alle vier Ebenen — System Context, Container, Component und Code. Klicken Sie auf einen beliebigen Service, um in seine Internals einzutauchen. Folgen Sie einer Beziehung quer durch den Stack.

Drift-Erkennung. Archyl vergleicht kontinuierlich Ihre dokumentierte Architektur mit dem tatsächlichen Code in Ihren Repositories. Wenn Ihr Katalog sagt „Service A ruft Service B auf", aber der Code das vor sechs Monaten eingestellt hat, finden Sie es heraus — anstatt es während eines Incidents zu entdecken.

Architektur-Konformitätsregeln. Kodifizieren Sie „kein Service außerhalb der Payment-Domäne darf legacy-auth-api aufrufen" oder „alle externen Aufrufe müssen über das API-Gateway gehen". Archyl setzt sie automatisch durch und meldet Verstöße bei jedem PR.

API-Vertrags-Intelligenz. Die OpenAPI-Specs, die Sie in Backstage gefüttert haben, leben jetzt innerhalb der Architektur, verknüpft mit Produzenten und Konsumenten. Breaking Change in news-api? Sehen Sie genau, welche nachgelagerten Services davon abhängen.

DORA-Metriken an die Architektur gebunden. Verbinden Sie Deployment-Frequenz, Lead Time, Change Failure Rate und MTTR mit spezifischen Systemen, Containern und Teams. Sehen Sie, welche Teile Ihrer Architektur gesund sind und welche in Schwierigkeiten stecken.

Architecture Decision Records. Haben Sie endlich einen Ort, um das Warum neben dem Was festzuhalten, direkt mit den betroffenen Systemen und Components verknüpft.

MCP-Integration. Jeder AI-Coding-Agent in Ihrem Team — Claude Code, Cursor, Windsurf — teilt denselben Architektur-Kontext. Hören Sie auf, Ihrem LLM immer wieder zu erklären, wie Ihre Services zusammenpassen.

Der Backstage-Katalog beantwortet „welche Services laufen bei uns?". Archyl beantwortet „wie sind sie verbunden, was driftet, was ist gefährdet, und wo sollten wir investieren?". Den Katalog zu importieren bedeutet, dass Sie sich nicht zwischen den beiden entscheiden müssen.

Für AI-Agent-Workflows

Derselbe Import ist über Archyls MCP-Server verfügbar. Verweisen Sie Claude Code, Cursor oder einen beliebigen AI-Coding-Agent auf das import_dsl-Tool mit format: "backstage" und dem Inhalt Ihrer entities.json — und Ihre Architektur landet, ohne dass jemand einen Browser anfasst.

Verwenden Sie das import_dsl-Tool mit:
- projectId: <Ihre Projekt-UUID>
- content: <Inhalt von entities.json>
- format: "backstage"

Nützlich, wenn Sie Katalog-Syncs aus CI skripten oder wenn Sie möchten, dass Ihr AI-Assistent das Modell nach einem größeren Backstage-Update aktualisiert.

Probieren Sie es jetzt aus

Wenn Ihr Team heute Backstage betreibt, sind Sie buchstäblich einen curl von einer vollständigen C4-Architektur entfernt.

  1. Führen Sie das curl oben aus.
  2. Öffnen Sie Archyl, klicken Sie auf Projekt importieren, wählen Sie Backstage.
  3. Beobachten Sie, wie Ihre Services, APIs, Queues und Datenbanken in eine navigierbare Architektur einrasten.

Der Import funktioniert in jedem Plan, einschließlich der kostenlosen Stufe. Wir denken nicht, dass Ihre Entscheidung davon abhängen sollte, ob Ihr Katalog portabel ist — sie sollte davon abhängen, was Sie als Nächstes damit tun möchten.

Ihr Backstage-Katalog wartet schon lange darauf, eine Architektur zu werden. Machen Sie ihn zu einer.