Architektur als Code

Mit Archyl definieren Sie Ihre gesamte C4-Architektur in einer einzigen YAML-Datei — archyl.yaml. Checken Sie sie in Ihr Repository ein, bearbeiten Sie sie zusammen mit Ihrem Code und lassen Sie CI/CD Ihre Diagramme automatisch synchron halten.
Überblick
Die Datei archyl.yaml ist eine deklarative Beschreibung Ihrer Architektur. Sie unterstützt:
- Alle vier C4-Ebenen (Systeme, Container, Komponenten, Code)
- Beziehungen zwischen beliebigen Elementen
- Technologien, Umgebungen und Releases
- ADRs, Dokumentation, API-Verträge und Event-Kanäle
- Visuelle Overlays zur Gruppierung im Diagramm
- Monorepo-Unterstützung über
include
Sie können die Datei von Hand schreiben, aus einem bestehenden Projekt exportieren oder beide Arbeitsweisen kombinieren.
Dateiformat
Archyl sucht die DSL-Datei im Stammverzeichnis des Repositorys und probiert diese Namen in folgender Reihenfolge:
archyl.yaml.archyl.yamlarchyl.yml.archyl.yml
Schema-Referenz
Grundstruktur
version: "1.0"
project:
name: My Platform
description: E-commerce platform serving 10M users
tags: [e-commerce, saas]
technologies: [...]
environments: [...]
systems: [...]
relationships: [...]
overlays: [...]
events: [...]
api_contracts: [...]
adrs:
folder: docs/adrs
records: [...]
docs:
folder: docs
records: [...]
releases: [...]
include: [...]
Nur version ist erforderlich. Alle anderen Abschnitte sind optional — nehmen Sie nur auf, was Sie brauchen.
Systeme (C4-Ebene 1)
Systeme sind die Elemente der obersten Ebene im C4-Modell.
systems:
- name: Payment Service
description: Handles all payment processing
type: software_system # person | software_system | external_system
external: false
tags: [payments, critical]
technologies: [Go, PostgreSQL]
owners:
teams: [backend-team]
users: [vincent]
containers: [...]
| Feld | Erforderlich | Beschreibung |
|---|---|---|
name |
Ja | Eindeutiger Systemname |
description |
Nein | Was dieses System tut |
type |
Nein | person, software_system oder external_system |
external |
Nein | Ob es sich um ein externes System handelt |
tags |
Nein | Tags zur Kategorisierung |
technologies |
Nein | Verwendete Technologien (verweist auf den Technologiekatalog) |
owners |
Nein | Verantwortliche Teams und Benutzer |
containers |
Nein | Verschachtelte Container (C4-Ebene 2) |
Container (C4-Ebene 2)
Container sind in ihrem übergeordneten System verschachtelt.
systems:
- name: Payment Service
containers:
- name: API Gateway
description: REST API for payment operations
type: api
tags: [rest, public]
technologies: [Go, Fiber]
owners:
teams: [backend-team]
components: [...]
Verfügbare Containertypen: web_app, mobile_app, desktop_app, api, database, file_storage, message_queue, cache, service, function, worker, consumer, infrastructure, gateway, library.
Wenn Sie include für Monorepo-Dateien verwenden, geben Sie mit parent_system an, zu welchem System dieser Container gehört:
# In services/payments/archyl.yaml
containers:
- name: Payments API
parent_system: Payment Service
type: api
Komponenten (C4-Ebene 3)
Komponenten sind in ihrem übergeordneten Container verschachtelt.
containers:
- name: API Gateway
components:
- name: PaymentHandler
description: HTTP handler for payment endpoints
type: handler
file: internal/handler/payment.go
tags: [http]
technologies: [Go]
code: [...]
Verfügbare Komponententypen: controller, service, repository, handler, middleware, model, util, config, adapter, port, resource, module, job, bundle, plugin, workflow, activity, entity.
Code-Elemente (C4-Ebene 4)
Code-Elemente sind in ihrer übergeordneten Komponente verschachtelt.
components:
- name: PaymentHandler
code:
- name: ProcessPayment
description: Handles payment processing requests
type: function
language: go
file: internal/handler/payment.go
line_start: 42
line_end: 87
visibility: public
signature: "func (h *PaymentHandler) ProcessPayment(c *fiber.Ctx) error"
methods:
- name: validate
signature: "func validate(req PaymentRequest) error"
return_type: error
visibility: private
properties:
- name: maxRetries
type: int
visibility: private
readonly: true
Verfügbare Typen für Code-Elemente: class, interface, struct, function, method, enum, constant, type.
Beziehungen
Beziehungen verbinden zwei beliebige Elemente; verschachtelte Elemente werden in Punktnotation referenziert.
relationships:
- from: Payment Service.API Gateway
to: Payment Service.Database
label: Reads/writes payment data
type: uses
technologies: [SQL, PostgreSQL]
tags: [data-access]
style:
color: "#6366f1"
width: 2
style: solid # solid | dashed | dotted
animated: false
Format der Punktnotation: System.Container.Component.CodeElement. Verwenden Sie nur so viele Ebenen wie nötig — Payment Service referenziert das System, Payment Service.API Gateway einen Container.
Verfügbare Beziehungstypen: uses, depends_on, calls, reads_from, writes_to, sends_to, receives_from, implements, extends, contains, deployed_on, provisions, publishes_to, consumes_from.
Technologien
Definieren Sie einen Katalog der Technologien, die in Ihrer Architektur zum Einsatz kommen.
technologies:
- name: Go
description: Primary backend language
category: programming_language
icon: go
- name: PostgreSQL
description: Main relational database
category: database
icon: postgresql
Verfügbare Kategorien: programming_language, framework, database, message_broker, object_storage, transport_protocol, cloud_service, devops_tool, library, runtime, cache, other.
Umgebungen
Definieren Sie Deployment-Umgebungen für Ihre Releases.
environments:
- name: Production
color: "#22c55e"
- name: Staging
color: "#f59e0b"
- name: Development
color: "#6366f1"
Releases
Verfolgen Sie versionierte Deployments über Umgebungen und Elemente hinweg.
releases:
- version: "2.4.0"
status: deployed # planned | in_progress | deployed | rolled_back | failed
changelog: "Added payment retry logic and improved error handling"
environment: Production
container: Payment Service.API Gateway
released_at: "2026-03-10T14:00:00Z"
source: github_action
source_url: "https://github.com/org/repo/actions/runs/12345"
Event-Kanäle
Definieren Sie asynchrone Kommunikation zwischen Services.
events:
- name: PaymentCompleted
description: Fired when a payment is successfully processed
direction: produce # produce | consume
broker: kafka # kafka | nats | sqs | rabbitmq | redis | pulsar | custom
topic: payments.completed
schema_format: json_schema # json_schema | avro | protobuf | text
schema: |
{ "type": "object", "properties": { "paymentId": { "type": "string" } } }
links:
- Payment Service.API Gateway
API-Verträge
Hängen Sie API-Spezifikationen an Ihre Architektur.
api_contracts:
- name: Payment API
description: REST API for payment operations
type: http # http | grpc | graphql | async
version: "2.0"
endpoint: /api/v2/payments
file: docs/openapi.yaml # path to spec file in repo
links:
- Payment Service.API Gateway
Mit file verweisen Sie auf eine Spezifikationsdatei im Repository, mit content binden Sie die Spezifikation direkt inline ein.
Architecture Decision Records (ADRs)
adrs:
folder: docs/adrs # optional: path to ADR folder in repo
records:
- title: Use event-driven architecture for payments
number: 7
status: accepted # proposed | accepted | deprecated | superseded
date: "2026-02-15"
context: We need to decouple payment processing from order management
decision: Use Kafka events for async communication between services
consequences: Added complexity but improved resilience and scalability
tags: [architecture, messaging]
links:
- Payment Service
Dokumentation
docs:
folder: docs # optional: path to docs folder in repo
records:
- title: Payment Processing Guide
file: docs/payments.md # path to markdown file in repo
tags: [payments, guide]
links:
- Payment Service.API Gateway
Mit file verweisen Sie auf eine Markdown-Datei im Repository, mit content binden Sie den Inhalt direkt inline ein.
Overlays
Visuelle Gruppierungen, die im Diagramm angezeigt werden.
overlays:
- name: Payment Domain
description: All payment-related services
color: "#6366f1"
level: 2 # C4 level (1=system, 2=container, 3=component, 4=code)
elements:
- Payment Service.API Gateway
- Payment Service.Database
- Payment Service.Worker
Include (Monorepo-Unterstützung)
In Monorepos verteilen Sie Ihre Architektur auf mehrere Dateien und führen sie zusammen:
include:
- services/payments/archyl.yaml
- services/orders/archyl.yaml
- services/users/archyl.yaml
Jede eingebundene Datei folgt demselben Schema. Verwenden Sie parent_system an Containern, um anzugeben, zu welchem System sie gehören, wenn sie in einer separaten Datei definiert sind.
Vollständiges Beispiel
version: "1.0"
project:
name: E-Commerce Platform
description: Online marketplace with payment processing
tags: [e-commerce, saas, marketplace]
technologies:
- name: Go
category: programming_language
- name: React
category: framework
- name: PostgreSQL
category: database
- name: Kafka
category: message_broker
- name: Redis
category: cache
environments:
- name: Production
color: "#22c55e"
- name: Staging
color: "#f59e0b"
systems:
- name: Storefront
description: Customer-facing web application
type: software_system
technologies: [React]
containers:
- name: Web App
type: web_app
technologies: [React]
- name: BFF
description: Backend for frontend
type: api
technologies: [Go]
- name: Payment Service
description: Handles payment processing
type: software_system
technologies: [Go, PostgreSQL]
containers:
- name: API
type: api
technologies: [Go]
components:
- name: PaymentHandler
type: handler
- name: PaymentService
type: service
- name: PaymentRepository
type: repository
- name: Database
type: database
technologies: [PostgreSQL]
- name: Worker
type: worker
technologies: [Go]
- name: Stripe
description: Third-party payment processor
type: external_system
external: true
relationships:
- from: Storefront.Web App
to: Storefront.BFF
label: API calls
type: uses
technologies: [HTTPS]
- from: Storefront.BFF
to: Payment Service.API
label: Process payments
type: calls
technologies: [gRPC]
- from: Payment Service.API
to: Payment Service.Database
label: Reads/writes payment data
type: uses
technologies: [SQL]
- from: Payment Service.API
to: Stripe
label: Process charges
type: calls
technologies: [HTTPS]
- from: Payment Service.Worker
to: Payment Service.Database
label: Polls for pending payments
type: reads_from
events:
- name: PaymentCompleted
broker: kafka
topic: payments.completed
direction: produce
links:
- Payment Service.API
overlays:
- name: Payment Domain
level: 2
color: "#6366f1"
elements:
- Payment Service.API
- Payment Service.Database
- Payment Service.Worker
releases:
- version: "1.2.0"
status: deployed
environment: Production
container: Payment Service.API
changelog: Added retry logic for failed charges
released_at: "2026-03-01T10:00:00Z"
Synchronisierung aus einem Repository
Enthält Ihr Repository eine archyl.yaml, können Sie sie direkt in der Archyl-Oberfläche synchronisieren:
- Gehen Sie zu Projekteinstellungen > Architektur als Code
- Klicken Sie auf Jetzt synchronisieren
Archyl ruft die Datei vom Standard-Branch Ihres Repositorys ab (oder von dem in den DSL-Einstellungen konfigurierten Branch) und importiert sie. Bereits vorhandene Elemente werden aktualisiert, neue Elemente werden erstellt.
CI/CD-Integration
GitHub Action (offiziell)
Die offizielle GitHub Action archyl-com/actions/sync ist der einfachste Weg, Ihre Architektur synchron zu halten. Sie liest Ihre archyl.yaml, überträgt sie an die Archyl-API und meldet, was erstellt oder aktualisiert wurde.
Minimale Einrichtung:
name: Sync Architecture
on:
push:
branches: [main]
paths: ['archyl.yaml']
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: archyl-com/actions/sync@v1
with:
api-key: ${{ secrets.ARCHYL_API_KEY }}
project-id: 'your-project-uuid'
Mit Zusammenfassung als Ausgabe:
- uses: archyl-com/actions/sync@v1
id: sync
with:
api-key: ${{ secrets.ARCHYL_API_KEY }}
project-id: 'your-project-uuid'
- run: echo "${{ steps.sync.outputs.summary }}"
Eigener Dateipfad (Monorepo):
- uses: archyl-com/actions/sync@v1
with:
api-key: ${{ secrets.ARCHYL_API_KEY }}
project-id: 'your-project-uuid'
file: 'services/payments/archyl.yaml'
Selbst gehostetes Archyl:
- uses: archyl-com/actions/sync@v1
with:
api-url: 'https://archyl.your-company.com'
api-key: ${{ secrets.ARCHYL_API_KEY }}
project-id: 'your-project-uuid'
Action-Eingaben
| Eingabe | Erforderlich | Standard | Beschreibung |
|---|---|---|---|
api-key |
Ja | Archyl-API-Schlüssel mit Schreibberechtigung | |
project-id |
Ja | UUID des Archyl-Projekts | |
api-url |
Nein | https://api.archyl.com |
Basis-URL der API (für selbst gehostete Instanzen) |
file |
Nein | archyl.yaml |
Pfad zur YAML-Datei relativ zum Stammverzeichnis des Repositorys |
Action-Ausgaben
| Ausgabe | Beschreibung |
|---|---|
systems-created |
Anzahl der erstellten Systeme |
containers-created |
Anzahl der erstellten Container |
components-created |
Anzahl der erstellten Komponenten |
relationships-created |
Anzahl der erstellten Beziehungen |
summary |
Lesbare Zusammenfassung des Synchronisierungsergebnisses |
GitLab CI/CD
sync-architecture:
stage: deploy
only:
changes: [archyl.yaml]
script:
- |
curl -sf -X POST https://your-instance.com/api/v1/projects/${PROJECT_ID}/dsl/ingest \
-H "X-API-Key: ${ARCHYL_API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"content\": $(cat archyl.yaml | jq -Rs .)}"
REST-API
Sie können DSL-Inhalte aus jedem CI/CD-System oder Skript übertragen:
curl -X POST https://your-instance.com/api/v1/projects/{projectId}/dsl/ingest \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d "{\"content\": $(cat archyl.yaml | jq -Rs .)}"
Der Ingest-Endpoint gibt eine Zusammenfassung dessen zurück, was erstellt wurde:
{
"source": "api",
"import": {
"systemsCreated": 2,
"containersCreated": 5,
"componentsCreated": 12,
"codeElementsCreated": 0,
"relationshipsCreated": 8,
"overlaysCreated": 1,
"technologiesCreated": 4,
"adrsCreated": 0,
"docsCreated": 0,
"eventsCreated": 1,
"apiContractsCreated": 0,
"environmentsCreated": 2,
"releasesCreated": 1
}
}
Export als YAML
Sie können jedes bestehende Projekt als archyl.yaml-Datei exportieren:
- Öffnen Sie Ihr Projekt
- Klicken Sie in der Toolbar auf Exportieren
- Wählen Sie YAML (Architektur als Code)
Dadurch entsteht eine vollständige archyl.yaml, die Sie in Ihr Repository einchecken können. So lässt sich die Datei bequem aus einem bestehenden Projekt oder einer per KI entdeckten Architektur erzeugen.
Der Export ist auch über die API möglich:
curl -H "X-API-Key: your-api-key" \
https://your-instance.com/api/v1/projects/{projectId}/dsl/export \
-o archyl.yaml
JSON Schema für IDE-Unterstützung
Archyl stellt ein JSON Schema für archyl.yaml-Dateien bereit, damit Ihr Editor Autovervollständigung und Validierung anbieten kann. Das Schema ist hier verfügbar:
https://your-instance.com/api/v1/dsl/schema
VS Code
Fügen Sie dies zu Ihrer archyl.yaml hinzu, um die Schema-Validierung zu aktivieren:
# yaml-language-server: $schema=https://your-instance.com/api/v1/dsl/schema
version: "1.0"
Oder konfigurieren Sie es global in den VS-Code-Einstellungen:
{
"yaml.schemas": {
"https://your-instance.com/api/v1/dsl/schema": ["archyl.yaml", ".archyl.yaml"]
}
}
Bild- und PDF-Export
Archyl kann Ihre Diagramme auch als Bilder für Präsentationen und Dokumente exportieren.
Verfügbare Formate
| Format | Am besten für |
|---|---|
| PNG | Präsentationen, Dokumente, Teilen im Chat |
| SVG | Design-Tools, Web-Einbettung, Druck |
| Formale Dokumentation, Archivierung |
So exportieren Sie
- Navigieren Sie zur C4-Ebene, die Sie exportieren möchten
- Klicken Sie in der Toolbar auf Exportieren
- Wählen Sie Ihr Format (PNG, SVG oder PDF)
- Konfigurieren Sie die Optionen (Hintergrund, Qualität, Viewport)
- Klicken Sie auf Exportieren
Aktivieren Sie Alle Ebenen exportieren, um für jede C4-Ebene eine eigene Datei zu erzeugen.
Export-Optionen
- Hintergrund: Den dunklen Canvas-Hintergrund einbeziehen oder transparent exportieren
- Qualität (nur PNG): Standard-, Hoch- oder Druckauflösung
- Viewport: An den Inhalt anpassen, Padding einschließen oder die aktuelle Ansicht exportieren
Projekte importieren
Sie können ein neues Projekt erstellen, indem Sie aus mehreren Formaten importieren. Archyl unterstützt fünf Importquellen:
| Format | Dateityp | Quell-Tool |
|---|---|---|
| Archyl YAML | .yaml / .yml |
Archyls natives Format |
| Structurizr DSL | .dsl |
Structurizr |
| LikeC4 | .c4 / .likec4 |
LikeC4 |
| IcePanel JSON | .json |
IcePanel |
| Backstage JSON | .json |
Backstage |
So importieren Sie
- Klicken Sie in Ihrer Projektliste auf Projekt importieren
- Wählen Sie den Tab des Quellformats (Archyl YAML, Structurizr DSL, LikeC4, IcePanel oder Backstage)
- Laden Sie die Datei hoch oder fügen Sie ihren Inhalt ein
- Klicken Sie auf Validieren, um eine Vorschau dessen zu sehen, was erstellt wird
- Klicken Sie auf Projekt erstellen
Der gesamte Vorgang dauert weniger als eine Minute. Alle Systeme, Container, Komponenten, Beziehungen, Technologien und Tags werden automatisch importiert.
Projektname und Beschreibung
Zum Erstellen eines Projekts ist ein Name erforderlich, und jedes Format führt ihn an einer anderen Stelle. Ein fehlender Name ist die häufigste Ursache für einen abgelehnten Import.
| Format | Projektname | Projektbeschreibung |
|---|---|---|
| Archyl YAML | project.name — erforderlich |
project.description |
| Structurizr DSL | Der Workspace-Name — erforderlich | Die Workspace-Beschreibung |
| LikeC4 | Erstes Element der obersten Ebene, sonst Imported LikeC4 Project |
Nicht verfügbar |
| IcePanel JSON | Das domain-Objekt, sonst Imported IcePanel Project |
Nicht verfügbar |
| Backstage JSON | Immer Imported Backstage Catalog |
Nicht verfügbar |
Nur Archyl YAML und Structurizr DSL können an dieser Prüfung scheitern. Die anderen Formate greifen immer auf einen generierten Namen zurück, den Sie nach dem Import ändern können.
Bei Structurizr sind Name und Beschreibung die beiden optionalen Zeichenketten im workspace-Kopf:
workspace "My Platform" "Microservices architecture" {
model {
user = person "User"
platform = softwareSystem "My Platform" {
api = container "API" "REST API" "Go"
}
user -> api "Uses"
}
}
Ein reines workspace { ... } wird korrekt geparst, kann aber kein Projekt erstellen — Archyl lehnt es ab und fordert Sie auf, dem Workspace einen Namen zu geben. Der Import in ein bestehendes Projekt hat diese Anforderung nicht: Dort wird der Workspace-Name ignoriert, weil das Projekt bereits einen Namen hat.
Structurizr DSL-Import
Archyl parst Structurizrs .dsl-Workspace-Dateien und extrahiert das vollständige C4-Modell:
- Elemente vom Typ
person,softwareSystem,containerundcomponent - Alle
->-Beziehungen mit Beschreibungen und Technologien - Erkennung externer Systeme anhand von Tags
- Extraktion von Technologien aus positionellen Argumenten
- Gruppen werden auf Tags abgebildet
Views, Styles, Themes und Deployment-Knoten werden übersprungen (Archyl hat eine eigene visuelle Ebene).
Workspace-Name und -Beschreibung werden zu Projektname und -beschreibung — siehe den Abschnitt Projektname und Beschreibung oben. Ein Workspace ohne Namen kann in ein bestehendes Projekt importiert werden, aber kein neues erstellen.
Workspaces über mehrere Dateien (!include)
Ein auf mehrere Dateien verteilter Workspace — !include systems/payments.dsl und ähnliche — lässt sich nicht als Einzeldatei importieren, weil die eingebundenen Dateien zum Auflösen fehlen. Laden Sie stattdessen den gesamten Workspace als .zip hoch, im Tab Structurizr DSL: Die Dateien des Archivs werden entpackt und jedes !include wird gegen sie aufgelöst.
- Einstiegspunkt ist
workspace.dsl, sofern vorhanden, sonst die am wenigsten tief liegende.dsl-Datei. Archyl nennt die verwendete Datei. - Pfade werden relativ zur einbindenden Datei aufgelöst, verschachtelte Includes funktionieren also.
- Das Einbinden eines Verzeichnisses zieht jede
.dsldirekt darin in Namensreihenfolge herein. - Include-Zyklen werden unterbrochen und gemeldet, statt den Import scheitern zu lassen.
- Entfernte Ziele (
!include https://…) werden abgelehnt, Pfade außerhalb des Archivs übersprungen.
Alles Unauflösbare wird zu einer Warnung am Importergebnis — der Rest des Workspace wird trotzdem importiert.
Grenzen für Archive:
| Grenze | Wert |
|---|---|
| Archivgröße | 10 MiB |
| Dateien im Archiv | 500 |
| Entpackte Gesamtgröße | 50 MiB |
| Größe einer einzelnen Datei | 5 MiB (eine größere Datei wird mit einer Warnung übersprungen) |
| Verschachtelungstiefe von Includes | 10 Ebenen |
Nur Dateien vom Typ .dsl, .md, .json, .yaml, .yml und .txt werden übernommen; alles andere im Archiv wird ignoriert.
Über die API senden Sie das Archiv als Multipart-Formulardaten im Feld file, optional mit einem Feld entry, das den Einstiegspunkt benennt: POST /api/v1/dsl/validate-archive prüft es, POST /api/v1/projects/{id}/dsl/import-archive importiert es in ein Projekt und POST /api/v1/dsl/import-project-archive erstellt daraus ein Projekt. Das MCP-Tool import_dsl und die Repository-Synchronisierung lesen eine einzelne Datei und lösen !include nicht auf.
LikeC4-Import
Archyl ist das erste Tool, das LikeC4-Dateien importiert. Der Importer unterstützt die Besonderheiten von LikeC4:
- Benutzerdefinierte Elementarten aus
specification-Blöcken werden auf C4-Ebenen abgebildet - Verschachtelte Elementhierarchien werden in Systeme, Container und Komponenten aufgelöst
- Eigenschaften
technology:unddescription:(mit oder ohne Doppelpunkt-Syntax) #hashtag-Tags werden in Standard-Tags umgewandelt- Das Tag
#externalwird zur Einordnung als externes Element erkannt - Mehrere
model-Blöcke werden automatisch zusammengeführt - Zeichenketten in einfachen und dreifachen Anführungszeichen werden unterstützt
IcePanel JSON-Import
Das JSON-Exportformat von IcePanel wird vollständig unterstützt:
- Objekttypen
system,actor,app,storeundcomponentwerden auf C4-Elemente abgebildet - Das Feld
external: truezur Einordnung als externes System modelConnectionswerden auf Beziehungen abgebildettagIdswerden über dastags-Array in Tag-Namen aufgelöstdomain-Objekte dienen als Projektname
Backstage-Import
Archyl importiert das Software-Catalog-JSON, das der Backstage-Endpoint /api/catalog/entities zurückgibt:
System-Entitäten werden zu Archyl-Systemen (Namenskollisionen über Namespaces hinweg werden automatisch aufgelöst)Component- undResource-Entitäten werden als Container unter ihrem zugehörigen System eingehängt (überspec.systemoder diepartOf-Relation)- Components/Resources ohne übergeordnetes System werden unter einem synthetischen System Uncategorized gruppiert
Resource-Typen werden auf Archyl-Containertypen abgebildet:s3-bucket→file_storage;rds-instance,dynamo-db-table,valkey-cluster,opensearch-domain→database;kafka-topic,sqs-queue→message_queue;repository→library; alles andere →infrastructureComponent-Typen werden abgebildet:service→service,cronworkflow→worker,website→web_app,library→libraryAPI-Entitäten werden als API-Verträge importiert; die inlinespec.definition(OpenAPI / gRPC / GraphQL / AsyncAPI) bleibt als Inhalt erhalten und wird mit den bereitstellenden bzw. konsumierenden Komponenten verknüpftdependsOn,consumesApi,producesTo,consumesFrom,versionedIn(und ihre Umkehrungen) werden in Archyl-Beziehungen übersetztmetadata.namespace,spec.lifecycleundspec.typewerden als Tags übernommenUser- undGroup-Entitäten werden übersprungen — der Personen- und Team-Graph von Backstage ist kein C4-Konzept
So exportieren Sie Ihren Katalog:
curl -H "Authorization: Bearer $BACKSTAGE_TOKEN" \
https://backstage.your-company.com/api/catalog/entities \
-o entities.json
Ziehen Sie entities.json anschließend in den Tab Backstage des Import-Dialogs. Ressourcenlisten aus großen Katalogen können Tausende von Containern erzeugen — prüfen Sie das Ergebnis und löschen Sie, was Sie nicht benötigen.
Import via MCP (KI-Agenten)
Dieselbe Import-Funktionalität steht über das MCP-Tool import_dsl zur Verfügung:
Use the import_dsl tool with:
- projectId: your project UUID
- content: the DSL/JSON content
- format: "archyl", "structurizr", "likec4", "icepanel", or "backstage"
So können KI-Coding-Agenten (Claude Code, Cursor, Windsurf) Architekturdateien programmatisch importieren.
Import in bestehende Projekte
Sie können auch in ein bestehendes Projekt importieren (nicht nur neue Projekte erstellen):
- Öffnen Sie Ihr Projekt
- Gehen Sie zu Architektur als Code
- Klicken Sie auf Importieren
- Wählen Sie das Format und laden Sie die Datei hoch
Bereits vorhandene Elemente werden aktualisiert, neue Elemente werden erstellt.
Nächste Schritte
- API-Übersicht — Vollständige API-Referenz für die DSL-Endpoints
- Teilen & Einbetten — Live-Diagramme teilen
- Release-Management — Deployments in Ihrer YAML verfolgen
- Webhook-Benachrichtigungen — Bei Architekturänderungen benachrichtigt werden