Architecture as Code: Ihr Systemdesign programmatisch definieren

Es gibt ein Muster im Software Engineering, das sich alle paar Jahre wiederholt. Eine Praxis, die manuell und visuell war, wird kodifiziert, versionskontrolliert und automatisiert -- und alles wird besser.

Es passierte mit Infrastruktur. Wir gingen vom Klicken durch Cloud-Konsolen zum Schreiben von Terraform-Dateien. Es passierte mit Konfiguration. Wir gingen vom Bearbeiten von Config-Dateien auf Servern zum Deklarieren des gewünschten Zustands in Kubernetes-Manifesten. Es passierte mit Datenbankschemas. Wir gingen vom manuellen Ausführen von SQL-Skripten zum Schreiben von Migrationsdateien.

Jetzt passiert es mit Architekturdokumentation. Architecture as Code ist die Praxis, Ihr Systemdesign programmatisch zu definieren -- in strukturierten Textdateien, die über dieselben Pipelines wie Ihr Anwendungscode versionskontrolliert, reviewed, getestet und deployed werden können.

Dieser Leitfaden behandelt alles, was Sie über Architecture as Code wissen müssen: was es ist, warum es wichtig ist, wie es sich von rein visuellen Ansätzen unterscheidet und wie Sie es in der Praxis umsetzen.

Was ist Architecture as Code?

Architecture as Code (AaC) ist die Praxis, Ihre Softwarearchitektur in maschinenlesbaren, menschlich schreibbaren Textdateien zu definieren. Statt Boxen und Pfeile in einem visuellen Tool zu zeichnen, beschreiben Sie Ihre Systems, Containers, Components und deren Relationships in einem strukturierten Format wie YAML, JSON oder einer zweckgebundenen DSL.

Hier ist ein einfaches Beispiel einer in YAML definierten Architektur:

version: "1.0"

project:
  name: "Payment Platform"
  description: "Verarbeitet alle Zahlungen für die Organisation"

systems:
  - name: Payment Platform
    type: software_system
    description: "Kern-Zahlungsverarbeitungssystem"
    containers:
      - name: Payment API
        type: api
        description: "REST API für Zahlungsoperationen"
        technologies: [Go, gRPC, OpenAPI]
      - name: Payment Processor
        type: service
        description: "Verarbeitet Zahlungstransaktionen"
        technologies: [Go]
      - name: Transaction Database
        type: database
        description: "Speichert Transaktionsdatensätze"
        technologies: [PostgreSQL]
      - name: Payment Queue
        type: queue
        description: "Asynchrone Zahlungsverarbeitungs-Queue"
        technologies: [Kafka]

  - name: Stripe
    type: external_system
    description: "Drittanbieter-Payment-Gateway"

relationships:
  - from: Payment API
    to: Payment Processor
    label: "Leitet Zahlungsanfragen weiter"
    type: uses
  - from: Payment Processor
    to: Transaction Database
    label: "Persistiert Transaktionen"
    type: writes_to
  - from: Payment Processor
    to: Payment Queue
    label: "Publiziert Zahlungs-Events"
    type: publishes_to
  - from: Payment Processor
    to: Stripe
    label: "Belastet Karten über"
    type: uses

Diese Datei ist die vollständige Single Source of Truth für die Architektur. Ein Tool wie Archyl liest sie, baut das C4-Modell auf, rendert interaktive Diagramme und hält alles synchron. Die Datei lebt in Ihrem Git-Repository, direkt neben dem Code, den sie beschreibt.

Warum rein visuelle Ansätze nicht ausreichen

Bevor es Architecture as Code gab, dokumentierten Teams ihre Architektur typischerweise mit visuellen Tools -- Lucidchart, draw.io, Miro oder Figma. Diese Tools sind hervorragend für Brainstorming und initiale Design-Sessions, haben aber fundamentale Einschränkungen als langfristige Dokumentation:

Keine Versionskontrolle

Visuelle Diagramme werden als binäre oder proprietäre Dateien gespeichert, die nicht sinnvoll gedifft werden können. Wenn jemand ein Diagramm ändert, können Sie sehen, dass es sich geändert hat, aber nicht was sich geändert hat. Es gibt kein Äquivalent zu git diff für eine draw.io-Datei. Sie können eine Diagrammänderung nicht in einem Pull Request reviewen wie eine Code-Änderung.

Mit Architecture as Code ist jede Änderung ein Text-Diff. Das Hinzufügen eines neuen Services sind ein paar Zeilen YAML. Das Umbenennen einer Komponente ist eine einzeilige Änderung. Reviewer können genau sehen, was sich geändert hat, warum es sich geändert hat (aus der Commit-Nachricht) und können genehmigen oder Änderungen anfordern.

Keine Automatisierung

Visuelle Diagramme existieren isoliert. Sie können keine Aktionen auslösen, keine Regeln validieren und nicht in CI/CD-Pipelines integriert werden. Wenn Ihr Diagramm sagt, Sie haben 10 Services, aber Ihr Kubernetes-Cluster 12 betreibt, erkennt nichts die Diskrepanz.

Architecture as Code ermöglicht Automatisierung. Sie können Validierungsregeln schreiben, die Ihre Architekturdefinition gegen Ihre tatsächliche Infrastruktur prüfen. Sie können Dokumentation aus der Architekturdatei generieren. Sie können Alerts auslösen, wenn die Architekturdatei von der Realität abweicht.

Keine Kollaboration im großen Maßstab

Wenn zwei Personen gleichzeitig dasselbe visuelle Diagramm bearbeiten, werden Konflikte üblicherweise dadurch gelöst, dass die Änderungen einer Person die der anderen überschreiben. Es gibt keine Merge-Strategie für visuelle Dateien.

Mit Architecture as Code gelten Standard-Git-Merge-Workflows. Zwei Teams können verschiedene Teile der Architekturdatei modifizieren, und Git mergt sie sauber. Wenn Konflikte auftreten, werden sie auf die gleiche Weise gelöst wie Code-Konflikte -- durch Diskussion und bewusste Entscheidung.

Keine Konsistenzgarantien

Ein visuelles Diagramm kann alles enthalten. Boxen können inkonsistent beschriftet sein. Pfeile können in verschiedenen Teilen desselben Diagramms unterschiedliche Bedeutungen haben. Es gibt kein Schema, keine Validierung, keine Durchsetzung von Namenskonventionen.

Architecture-as-Code-Dateien haben ein Schema. Das Tooling validiert die Datei bei jeder Änderung. Wenn Sie einen Container referenzieren, der nicht existiert, fängt die Validierung es ab. Wenn Sie einen ungültigen Beziehungstyp verwenden, wird er markiert, bevor die Änderung gemergt wird.

Lock-in und Portabilität

Visuelle Diagramme sind oft an das Tool gebunden, das sie erstellt hat. Von Lucidchart zu draw.io zu wechseln bedeutet, jedes Diagramm manuell neu zu erstellen. Von einem Architecture-as-Code-Tool zu einem anderen zu wechseln ist eine Formatkonvertierung -- automatisiert und wiederholbar.

Die Vorteile von Architecture as Code

Single Source of Truth

Wenn Ihre Architektur in einer einzelnen Datei (oder einem Satz von Dateien) definiert ist, gibt es genau einen Ort zum Nachschauen. Es gibt keine Frage, welches Diagramm aktuell ist, welche Confluence-Seite die neueste Version hat oder ob das PDF, das jemand letzten Monat per E-Mail verschickt hat, noch akkurat ist.

Code Review für Architekturänderungen

Das ist vielleicht der transformativste Vorteil. Wenn Architekturänderungen durch Pull Requests gehen, erhalten sie dieselbe Prüfung wie Code-Änderungen. Ein erfahrener Architekt kann eine vorgeschlagene Service-Aufteilung reviewen, bevor sie passiert. Das Team kann die Auswirkungen einer neuen Abhängigkeit diskutieren, bevor sie eingeführt wird.

+ - name: Notification Service
+   type: service
+   description: "Verarbeitet E-Mail-, SMS- und Push-Benachrichtigungen"
+   technologies: [Python, Celery, Redis]
+
+ - from: Order Service
+   to: Notification Service
+   label: "Löst Bestellbenachrichtigungen aus"
+   type: uses

Dieser Diff erzählt eine klare Geschichte: Jemand fügt einen Notification Service hinzu und verbindet ihn mit dem Order Service. Reviewer können Fragen stellen, alternative Technologien vorschlagen oder andere Service-Grenzen vorschlagen -- alles bevor eine einzige Zeile Anwendungscode geschrieben wurde.

Git-Historie ist Architektur-Historie

Jeder Commit in Ihre Architekturdatei erzeugt eine permanente Aufzeichnung, wie sich die Architektur entwickelt hat. Sie können Fragen beantworten wie:

• Wann wurde der Search Service hinzugefügt?
• Wer hat die Migration von MySQL zu PostgreSQL genehmigt?
• Wie sah die Architektur vor sechs Monaten aus?
• Wie hat sich die Anzahl der Services im Laufe der Zeit entwickelt?

Diese Historie ist unbezahlbar, um die Evolution Ihres Systems zu verstehen und neue Teammitglieder einzuarbeiten.

CI/CD-Integration

Architecture as Code integriert sich natürlich in Continuous-Integration- und Continuous-Deployment-Pipelines. Bei jedem Pull Request können Sie:

• Die Architekturdatei gegen ihr Schema validieren
• Conformance Rules prüfen (z. B. jeder Service muss einen dokumentierten Owner haben)
• Aktualisierte Diagramme generieren
• Drift zwischen der dokumentierten Architektur und dem laufenden System erkennen
• Die Architektur in Ihre Dokumentationsplattform publizieren

Das macht Architekturdokumentation zu einem lebendigen Artefakt statt einem statischen Dokument, das verfällt.

Refactoring und Automatisierung

Da Architekturdefinitionen strukturierte Daten sind, können Sie Skripte schreiben, um sie zu manipulieren. Müssen Sie einen Service über alle Beziehungen hinweg umbenennen? Ein einfaches Suchen-und-Ersetzen in einer YAML-Datei. Müssen Sie einen Bericht aller Services generieren, die PostgreSQL verwenden? YAML parsen und nach Technologie filtern. Müssen Sie eine Namenskonvention durchsetzen? Einen Linter schreiben.

Architecture-as-Code-Formate und DSLs

Mehrere Formate und DSLs existieren für die Definition von Architecture as Code. Hier ist ein Überblick über die gängigsten Ansätze.

Structurizr DSL

Von Simon Brown (dem Schöpfer des C4-Modells) erstellt, ist Structurizr DSL eines der frühesten Architecture-as-Code-Formate. Es verwendet eine benutzerdefinierte DSL-Syntax:

workspace {
    model {
        user = person "User"
        softwareSystem = softwareSystem "My Software System" {
            webapp = container "Web Application" "Delivers content" "Java"
            database = container "Database" "Stores data" "PostgreSQL"
        }
        user -> webapp "Uses"
        webapp -> database "Reads from and writes to"
    }
    views {
        systemContext softwareSystem {
            include *
            autolayout lr
        }
    }
}

Structurizr hat das Konzept von Architecture as Code für C4-Modelle pioniert. Allerdings hat seine benutzerdefinierte DSL-Syntax eine Lernkurve, und es erfordert Structurizr-spezifisches Tooling zum Rendern.

YAML-basierte Ansätze

YAML hat sich zum De-facto-Standard für deklarative Konfiguration im DevOps-Bereich entwickelt (Kubernetes, Docker Compose, GitHub Actions, abgesehen von Terraform HCL). YAML für Architekturdefinitionen zu verwenden hat den Vorteil der Vertrautheit -- die meisten Entwickler wissen bereits, wie man YAML liest und schreibt.

Archyls archyl.yaml-Format verfolgt diesen Ansatz:

version: "1.0"

systems:
  - name: E-Commerce Platform
    type: software_system
    containers:
      - name: Web Frontend
        type: webapp
        technologies: [React, TypeScript, Next.js]
      - name: API Service
        type: api
        technologies: [Go, gRPC]
        components:
          - name: Auth Handler
            type: handler
            technologies: [JWT, OAuth2]
          - name: Product Handler
            type: handler
            technologies: [REST]
      - name: Product Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: Web Frontend
    to: API Service
    label: "Macht API-Aufrufe an"
  - from: API Service
    to: Product Database
    label: "Liest/schreibt Produktdaten"

Die Verschachtelung spiegelt die C4-Hierarchie direkt wider: Systems enthalten Containers, Containers enthalten Components. Relationships verwenden menschenlesbare Namen mit Punkt-Notation zur Disambiguierung. Das Format ist grep-bar, diff-bar und erfordert kein spezialisiertes Tooling zum Lesen.

JSON und andere Formate

Einige Tools verwenden JSON, TOML oder andere strukturierte Formate. Das spezifische Format ist weniger wichtig als die Prinzipien: Die Architekturdefinition sollte textbasiert, versionskontrollierbar und maschinenlesbar sein.

Architecture as Code implementieren: Ein praktischer Workflow

Hier ist ein schrittweiser Workflow für die Einführung von Architecture as Code in Ihrem Team.

Schritt 1: Mit dem Bestehenden beginnen

Versuchen Sie nicht, Ihre gesamte Architektur am ersten Tag zu dokumentieren. Beginnen Sie mit dem Container-Diagramm -- der Service-Landschaft. Listen Sie jeden deploybaren Service auf, seinen Technologie-Stack und die wichtigsten Beziehungen zwischen Services.

Wenn Sie Archyl verwenden, können Sie das Modell entweder visuell in der UI erstellen und dann als archyl.yaml exportieren, oder die YAML-Datei von Grund auf schreiben. Beide Wege führen zum selben Ergebnis.

Schritt 2: In Ihr Repository committen

Platzieren Sie die Architekturdatei im Wurzelverzeichnis Ihres primären Repositorys (oder in einem dedizierten Architektur-Repository, wenn Ihre Codebasis auf viele Repos verteilt ist). Der Speicherort ist weniger wichtig als das Prinzip: Die Datei sollte in Git leben und durch Code Review gehen.

my-platform/
  archyl.yaml        # Architekturdefinition
  src/
  docker-compose.yml
  .github/
    workflows/
      architecture.yml  # CI-Pipeline für Architektur

Schritt 3: CI/CD-Sync einrichten

Konfigurieren Sie Ihre CI/CD-Pipeline, um die Architekturdatei bei jedem Merge in den Main Branch mit Archyl zu synchronisieren. Das stellt sicher, dass die visuellen Diagramme und die interaktive Dokumentation in Archyl immer die zuletzt committete Architektur widerspiegeln.

Ein GitHub-Actions-Workflow könnte so aussehen:

name: Sync Architecture

on:
  push:
    branches: [main]
    paths: [archyl.yaml]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync to Archyl
        run: |
          curl -X POST https://api.archyl.com/v1/sync \
            -H "Authorization: Bearer ${{ secrets.ARCHYL_TOKEN }}" \
            -H "Content-Type: application/yaml" \
            --data-binary @archyl.yaml

Schritt 4: Architekturänderungen über Pull Requests

Ab diesem Punkt folgen Architekturänderungen demselben Workflow wie Code-Änderungen:

1. Branch erstellen
2. Die archyl.yaml-Datei modifizieren
3. Einen Pull Request öffnen
4. Vom Team reviewen lassen
5. In Main mergen
6. CI/CD synchronisiert die Änderung zu Archyl

Das gibt Architekturänderungen dieselbe Sichtbarkeit, Verantwortlichkeit und Nachvollziehbarkeit wie Code-Änderungen.

Schritt 5: Conformance Rules hinzufügen

Wenn Ihre Architecture-as-Code-Praxis reift, fügen Sie Conformance Rules hinzu, die die Architekturdefinition automatisch validieren. Beispiele:

• Jeder Container muss mindestens eine Technologie angeben
• Jedes externe System muss eine Beschreibung haben
• Keine verwaisten Container (jeder Container muss mindestens eine Relationship haben)
• Namenskonventionen werden eingehalten (z. B. Services enden mit "Service")

Archyls Conformance-Rules-Engine kann diese Regeln automatisch evaluieren und Verstöße in der CI-Pipeline oder im Archyl-Dashboard melden.

Schritt 6: Die Definition im Laufe der Zeit weiterentwickeln

Beginnen Sie mit Systems und Containers. Fügen Sie Components hinzu, wenn bestimmte Services komplex genug werden, um eine interne Dokumentation zu rechtfertigen. Fügen Sie ADRs hinzu, wenn Sie wichtige architektonische Entscheidungen treffen. Fügen Sie API Contracts hinzu, wenn Sie Service-Grenzen formalisieren.

Die Architekturdatei wächst organisch mit Ihrem System. Es besteht keine Notwendigkeit, jedes Detail von Anfang an festzulegen.

Architecture as Code vs. Infrastructure as Code

Architecture as Code und Infrastructure as Code (IaC) sind komplementäre, aber unterschiedliche Praktiken.

Infrastructure as Code (Terraform, Pulumi, CloudFormation) definiert, was deployed und wie es konfiguriert wird. Es ist operationell: Es provisioniert Server, konfiguriert Netzwerke und verwaltet Cloud-Ressourcen.

Architecture as Code definiert, wie das System aussieht und wie seine Teile zusammenhängen. Es ist deskriptiv: Es dokumentiert die konzeptionelle Struktur, Technologieentscheidungen und Service-Grenzen.

Das ideale Setup kombiniert beides:

• Ihre Terraform-Dateien definieren die Infrastruktur
• Ihre archyl.yaml definiert die Architektur
• Conformance Rules prüfen, dass beide abgestimmt bleiben

Wenn Ihr Terraform einen neuen Service hinzufügt, aber die Architekturdatei ihn nicht erwähnt, erkennt die Drift Detection die Diskrepanz.

Architecture as Code mit KI-Assistenten

Einer der überzeugendsten Vorteile von Architecture as Code ist, dass KI-Assistenten es lesen und damit arbeiten können. Wenn Ihre Architektur in strukturiertem Text definiert ist, können Tools wie Claude Code und Cursor:

• Fragen über Ihre Architektur beantworten, indem sie die YAML-Datei abfragen
• Architekturänderungen basierend auf dem aktuellen Zustand vorschlagen
• Code generieren, der die dokumentierte Architektur respektiert (z. B. die richtige Datenbank für den richtigen Service verwenden)
• Inkonsistenzen zwischen Code und Architekturdefinition erkennen

Archyl geht mit seinem MCP Server weiter. KI-Assistenten lesen nicht nur die Architekturdatei -- sie können das Live-Architekturmodell abfragen, Relationships traversieren und sogar Modifikationen vorschlagen. Die Architektur wird zu einer programmierbaren, abfragbaren Datenquelle statt eines statischen Dokuments.

Häufige Fallstricke

Das Format überengineeren

Entwerfen Sie keine benutzerdefinierte DSL, wenn YAML oder ein bestehendes Format funktioniert. Das Ziel ist Adoption, und Adoption ist einfacher, wenn das Format vertraut ist. Die meisten Entwickler kennen YAML bereits von Docker Compose, Kubernetes und CI/CD-Konfigurationen.

Versuchen, alles abzubilden

Architecture as Code sollte die strukturellen Aspekte Ihres Systems erfassen: was existiert, wie Dinge verbunden sind und welche Technologien verwendet werden. Versuchen Sie nicht, operationelle Details (wie Skalierungsrichtlinien), Runtime-Konfigurationen (wie Umgebungsvariablen) oder Verhaltensspezifikationen (wie API-Antwortformate) in die Architekturdatei einzubetten.

Den Workflow nicht durchsetzen

Architecture as Code funktioniert nur, wenn Änderungen den definierten Workflow durchlaufen. Wenn Leute die Architekturdatei umgehen und Änderungen direkt im visuellen Tool vornehmen, wird die Datei veraltet. Etablieren Sie klare Konventionen darüber, welche Richtung autoritativ ist.

Die visuelle Ausgabe ignorieren

Architecture as Code ist kein Ersatz für visuelle Diagramme -- es ist ein besserer Weg, sie zu erzeugen. Die Textdatei ist die Source of Truth, aber die gerenderten Diagramme sind das, was die Leute tatsächlich täglich betrachten. Stellen Sie sicher, dass die visuelle Ausgabe zugänglich, aktuell und einfach zu navigieren ist.

Erste Schritte mit Archyl

Archyl ist von Grund auf so konzipiert, dass es Architecture as Code unterstützt. Die Plattform bietet:

• YAML-basierte DSL, die das vollständige C4-Modell mit Systems, Containers, Components, Relationships und Technologies abdeckt
• Bidirektionale Synchronisation -- visuell in der UI modellieren und als YAML exportieren, oder YAML schreiben und zur UI synchronisieren
• CI/CD-Integration für automatisierte Synchronisation bei jedem Commit
• Conformance Rules, die die Architekturdefinition gegen Ihre Standards validieren
• MCP Server, der die Architektur für KI-Assistenten abfragbar macht
• Kollaborationsfeatures mit Code Review, Kommentaren und Team-Ownership

Ob Sie bei null starten oder von visuellen Diagrammen migrieren -- Archyl macht Architecture as Code für Teams jeder Größe praxistauglich.

Starten Sie mit Architecture as Code und bringen Sie dieselbe Stringenz in Ihre Architekturdokumentation, die Sie bereits in Ihre Infrastruktur und Ihren Anwendungscode einbringen.