Wir haben gerade das Feature ausgeliefert, das Architekturdokumentation zu einem erstklassigen Bestandteil Ihrer Codebasis macht. Lernen Sie archyl.yaml kennen — eine deklarative DSL, die Ihr vollständiges C4-Modell beschreibt, in Git lebt, Code-Reviews durchläuft und sich automatisch über CI/CD synchronisiert.

Architecture as Code: Definieren Sie Ihr gesamtes C4-Modell in einer YAML-Datei

Architekturdiagramme haben ein Haltbarkeitsproblem. Man zeichnet sie nach einer Design-Session, sie sehen eine Woche lang toll aus, und dann entwickelt sich der Code weiter, während die Diagramme verrotten. Sechs Monate später starrt der neue Mitarbeiter auf ein Container-Diagramm, das drei Services zeigt, die im Q2 zusammengelegt wurden, und die zwei nicht erwähnt, die im Q3 gebaut wurden.

Dieses Problem beschäftigt uns seit dem ersten Tag bei Archyl. KI-Entdeckung hilft, die Dinge aktuell zu halten. Der visuelle Editor macht Updates schmerzlos. Aber es gibt eine Klasse von Teams — solche, die Infrastruktur als Code, Richtlinien als Code, alles als Code behandeln — die etwas Grundlegenderes wollten.

Sie wollten, dass ihre Architektur in Git lebt, neben dem Code, den sie beschreibt. Heute liefern wir genau das aus.

Was ist `archyl.yaml`?

Es ist eine einzelne YAML-Datei, die Ihre vollständige Architektur deklarativ beschreibt. Legen Sie sie im Stammverzeichnis Ihres Repositories ab, und sie wird zur Single Source of Truth für Ihr C4-Modell in Archyl.

So sieht eine minimale Datei aus:

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

Das ist alles. Archyl liest diese Datei, baut das vollständige C4-Modell auf, rendert Diagramme und hält alles synchronisiert. Kein Durchklicken von UIs, keine manuelle Synchronisierung, kein „Ich habe vergessen, das Diagramm zu aktualisieren."

Alles in einer Datei

Die DSL ist keine vereinfachte Teilmenge — sie deckt den vollen Umfang dessen ab, was Archyl modellieren kann:

Alle vier C4-Ebenen. Systeme enthalten Container, Container enthalten Komponenten, Komponenten enthalten Code-Elemente. Die YAML-Verschachtelung spiegelt die Hierarchie direkt wider.

Beziehungen mit Punkt-Notation. Verbinden Sie beliebige zwei Elemente mit lesbaren Referenzen wie Payment Service.API Gateway → Payment Service.Database. Keine UUIDs, keine kryptischen Bezeichner. Grep-freundlich, Diff-freundlich, menschenlesbar.

Technologien, Umgebungen und Releases. Definieren Sie Ihren Technologiekatalog, deklarieren Sie Deployment-Umgebungen (Staging, Produktion) und verfolgen Sie Releases — alles aus derselben Datei.

ADRs und Dokumentation. Betten Sie Ihre Architecture Decision Records ein oder verweisen Sie auf einen Ordner in Ihrem Repository. Ebenso für Projektdokumentation.

API-Verträge und Event-Kanäle. Deklarieren Sie Ihre OpenAPI-Spezifikationen, gRPC-Definitionen, Kafka-Topics und verknüpfen Sie sie mit den Komponenten, die sie bereitstellen oder konsumieren.

Visuelle Overlays. Gruppieren Sie Elemente im Diagramm mit benannten Overlays und steuern Sie Farben und Ebenen.

Monorepo-Unterstützung. Verwenden Sie include, um Ihre Architektur auf mehrere Dateien aufzuteilen — eine pro Service, Team oder Bounded Context — und Archyl führt sie automatisch zusammen.

Warum YAML?

Wir haben erwogen, eine eigene DSL-Syntax zu erstellen (wie Structurizrs DSL oder Terraforms HCL). Wir haben uns aus praktischen Gründen für YAML entschieden:

Keine Lernkurve. Jeder Entwickler kennt bereits YAML. Keine neue Syntax zu lernen, kein Parser zu installieren, kein Editor-Plugin erforderlich.
IDE-Unterstützung gratis. Wir veröffentlichen ein JSON Schema unter /api/v1/dsl/schema. Richten Sie Ihre IDE darauf und Sie erhalten Autovervollständigung, Validierung und Inline-Dokumentation ohne Archyl-spezifische Werkzeuge.
Diff-freundlich. YAML-Diffs sind sauber und lesbar in Pull Requests. Reviewer sehen sofort „ah, sie haben einen neuen Container zum Payment Service hinzugefügt und ihn mit Redis verbunden."
Tool-Ökosystem. Linters, Formatter, Template-Engines (Helm, Kustomize), alles funktioniert mit YAML out of the box.

Der Git-native Workflow

Hier liegt die wahre Stärke. Weil archyl.yaml in Ihrem Repository lebt, folgen Architekturänderungen demselben Workflow wie Code-Änderungen:

Branch. Erstellen Sie einen Feature-Branch, bearbeiten Sie das YAML.
Review. Öffnen Sie einen Pull Request. Ihr Team überprüft die Architekturänderung zusammen mit der Code-Änderung.
Merge. Nach der Genehmigung in main mergen.
Sync. Archyl erkennt die Änderung und aktualisiert die Diagramme automatisch.

Kein „das Diagramm sagt X aber der Code macht Y" mehr. Keine Architekturänderungen mehr, die das Review umgehen. Keine Dokumentation mehr, von der niemand weiß, dass sie aktualisiert wurde.

CI/CD-Integration

Wir haben eine erstklassige Integration mit CI/CD-Pipelines gebaut. Für GitHub liefern wir eine offizielle GitHub Action, die alles handhabt — Datei lesen, API aufrufen und berichten, was sich geändert hat.

GitHub Actions (offizielle Action):

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'

Das ist alles. Drei Zeilen Konfiguration und Ihre Architektur bleibt bei jedem Push synchron. Die Action unterstützt benutzerdefinierte Dateipfade (für Monorepos), selbst gehostete Archyl-Instanzen und stellt Outputs wie summary, systems-created und relationships-created für nachfolgende Schritte bereit.

GitLab CI:

sync-architecture:
  stage: deploy
  script:
    - |
      curl -X POST \
        https://api.archyl.com/api/v1/projects/$ARCHYL_PROJECT_ID/dsl/ingest \
        -H "X-API-Key: $ARCHYL_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$(cat archyl.yaml | jq -Rs .)\"}"
  only:
    changes:
      - archyl.yaml

Der /ingest-Endpoint akzeptiert API-Key-Authentifizierung, sodass kein OAuth-Flow in CI benötigt wird. Er importiert das vollständige Modell, erstellt oder aktualisiert jedes Element und gibt eine detaillierte Zusammenfassung der Änderungen zurück.

Sie können auch direkt über die Archyl-UI synchronisieren. Wenn Ihr Projekt ein verbundenes Git-Repository hat, klicken Sie auf „Jetzt synchronisieren" in den Architecture as Code-Einstellungen und Archyl holt die Datei direkt aus Ihrem Repository.

Bidirektional: Export und Import

Der Workflow ist nicht unidirektional. Haben Sie bereits ein Projekt im visuellen Editor von Archyl modelliert? Exportieren Sie es:

Export generiert ein vollständiges archyl.yaml aus Ihrem aktuellen Modell. Jedes System, Container, Komponente, Beziehung, Overlay, ADR, API-Vertrag, Event-Kanal, Release — alles in sauberes YAML serialisiert.
Import parst ein archyl.yaml und erstellt oder aktualisiert alle Elemente in Ihrem Projekt. Es ist idempotent: den gleichen Import zweimal durchzuführen erzeugt keine Duplikate. Elemente werden nach Name abgeglichen und upsertet.
Import as Project erstellt ein brandneues Projekt aus einer YAML-Datei. Legen Sie ein archyl.yaml ab und erhalten Sie ein vollständig gefülltes Projekt mit einem Klick.

Das bedeutet, Sie können in der UI starten, nach YAML exportieren, in Git committen und zum Code-First-Workflow wechseln — oder umgekehrt. Kein Lock-in auf einen der Ansätze.

Intelligente Referenzauflösung

Einer der kniffligsten Teile der DSL ist die Auflösung von Elementreferenzen in Beziehungen, Overlays, Events und API-Verträgen. Wir haben einen Resolver gebaut, der das natürlich handhabt:

Kurze Namen funktionieren bei Eindeutigkeit: API Gateway wird direkt aufgelöst, wenn nur ein Element diesen Namen hat.
Punkt-Notation disambiguiert: Payment Service.API Gateway vs Analytics.API Gateway.
Jede Tiefe funktioniert: System.Container.Component.CodeElement für tief verschachtelte Referenzen.

Der Resolver indiziert jedes Element auf jeder möglichen Pfadtiefe, sodass Sie immer die kürzeste eindeutige Referenz verwenden. Exports nutzen dieselbe Logik umgekehrt — und erzeugen die lesbarsten Referenzen.

Validierung ohne Seiteneffekte

Nicht sicher, ob Ihr YAML gültig ist? Der /validate-Endpoint (und der „Validieren"-Button im Import-Modal) parst und prüft Ihre Datei, ohne die Datenbank zu berühren:

Schema-Versionsprüfung
Pflichtfeld-Validierung
Erkennung doppelter Namen
Validierung von Typ-Aufzählungen (Container-Typen, Beziehungstypen, etc.)
Kreuzreferenz-Auflösung

Fehler kommen mit präzisen Pfaden zurück (systems[2].containers[1].name) und klaren Meldungen. Binden Sie es in einen Pre-Commit-Hook oder CI-Check ein und fangen Sie Probleme ab, bevor sie main erreichen.

Praxisnahe Muster

Das Monorepo

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

Jeder Service pflegt sein eigenes archyl.yaml, das seine Container und Komponenten definiert. Die Root-Datei führt sie zusammen, und service-übergreifende Beziehungen werden auf Root-Ebene definiert. Technologien und Umgebungen werden automatisch dedupliziert.

Der Bootstrapper

Neues Projekt starten? Erstellen Sie ein archyl.yaml, bevor Sie Code schreiben. Definieren Sie die Systeme und Container, die Sie bauen möchten. Nutzen Sie Archyls „Import as Project", um die Architektur sofort zu generieren. Während Sie entwickeln, entwickelt sich das YAML mit dem Code weiter.

Der Audit-Trail

Weil das YAML in Git liegt, bekommen Sie die vollständige Historie kostenlos. git log archyl.yaml zeigt jede Architekturänderung, wer sie gemacht hat, wann, und den PR, in dem sie besprochen wurde. Versuchen Sie das mal mit einem Diagramm-Tool.

Der Dokumentationsgenerator

Exportieren Sie Ihre Architektur nach YAML und leiten Sie sie durch eine beliebige Template-Engine, um Markdown-Docs, Confluence-Seiten oder interne Wikis zu generieren. Das strukturierte Format macht die Automatisierung trivial.

Was kommt als Nächstes

Das ist Version 1.0 des DSL-Formats. Hier ist, woran wir als Nächstes arbeiten:

Drift-Erkennung. Das YAML in Ihrem Repository mit dem Live-Modell vergleichen und Unterschiede hervorheben — Elemente, die in der UI hinzugefügt wurden, aber nicht in der Datei, oder umgekehrt.

PR-Vorschau-Kommentare. Wenn ein PR archyl.yaml ändert, kommentiert ein Bot mit einem visuellen Diff dessen, was sich in der Architektur geändert hat.

Schema-Evolution. Wenn wir neue Archyl-Features hinzufügen, wird die DSL wachsen. Wir werden Abwärtskompatibilität wahren und Migrationswerkzeuge bereitstellen.

Jetzt ausprobieren

Architecture as Code ist ab heute auf allen Archyl-Plänen verfügbar. Wenn Sie bereits ein Projekt haben:

Gehen Sie zur Architecture as Code-Seite in Ihrem Projekt
Klicken Sie auf Export, um Ihr archyl.yaml zu generieren
Committen Sie es in Ihr Repository
Fügen Sie die offizielle GitHub Action zu Ihrem Workflow hinzu und fertig

Wenn Sie neu starten, erstellen Sie ein archyl.yaml, nutzen Sie Import as Project, und Sie haben eine vollständig gerenderte C4-Architektur in Sekunden.

Ihre Architektur verdient dieselbe Sorgfalt wie Ihr Code. Versionieren Sie sie, überprüfen Sie sie, automatisieren Sie sie.

Neu bei C4? Starten Sie mit unserer Einführung in das C4-Modell. Möchten Sie, dass KI die initiale Architektur generiert? Siehe KI-gestützte Architekturentdeckung. Nutzen Sie bereits KI-Assistenten? Verbinden Sie sie über unseren MCP-Server.

Architecture as Code: Definieren Sie Ihr gesamtes C4-Modell in einer YAML-Datei - Archyl Blog