Architektur als Code

The whole model as code in the DSL editor

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:

  1. archyl.yaml
  2. .archyl.yaml
  3. archyl.yml
  4. .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:

  1. Gehen Sie zu Projekteinstellungen > Architektur als Code
  2. 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:

  1. Öffnen Sie Ihr Projekt
  2. Klicken Sie in der Toolbar auf Exportieren
  3. 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
PDF Formale Dokumentation, Archivierung

So exportieren Sie

  1. Navigieren Sie zur C4-Ebene, die Sie exportieren möchten
  2. Klicken Sie in der Toolbar auf Exportieren
  3. Wählen Sie Ihr Format (PNG, SVG oder PDF)
  4. Konfigurieren Sie die Optionen (Hintergrund, Qualität, Viewport)
  5. 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

  1. Klicken Sie in Ihrer Projektliste auf Projekt importieren
  2. Wählen Sie den Tab des Quellformats (Archyl YAML, Structurizr DSL, LikeC4, IcePanel oder Backstage)
  3. Laden Sie die Datei hoch oder fügen Sie ihren Inhalt ein
  4. Klicken Sie auf Validieren, um eine Vorschau dessen zu sehen, was erstellt wird
  5. 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, container und component
  • 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 .dsl direkt 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: und description: (mit oder ohne Doppelpunkt-Syntax)
  • #hashtag-Tags werden in Standard-Tags umgewandelt
  • Das Tag #external wird 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, store und component werden auf C4-Elemente abgebildet
  • Das Feld external: true zur Einordnung als externes System
  • modelConnections werden auf Beziehungen abgebildet
  • tagIds werden über das tags-Array in Tag-Namen aufgelöst
  • domain-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- und Resource-Entitäten werden als Container unter ihrem zugehörigen System eingehängt (über spec.system oder die partOf-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 → infrastructure
  • Component-Typen werden abgebildet: service → service, cronworkflow → worker, website → web_app, library → library
  • API-Entitäten werden als API-Verträge importiert; die inline spec.definition (OpenAPI / gRPC / GraphQL / AsyncAPI) bleibt als Inhalt erhalten und wird mit den bereitstellenden bzw. konsumierenden Komponenten verknüpft
  • dependsOn, consumesApi, producesTo, consumesFrom, versionedIn (und ihre Umkehrungen) werden in Archyl-Beziehungen übersetzt
  • metadata.namespace, spec.lifecycle und spec.type werden als Tags übernommen
  • User- und Group-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):

  1. Öffnen Sie Ihr Projekt
  2. Gehen Sie zu Architektur als Code
  3. Klicken Sie auf Importieren
  4. Wählen Sie das Format und laden Sie die Datei hoch

Bereits vorhandene Elemente werden aktualisiert, neue Elemente werden erstellt.

Nächste Schritte