← Zurück zum Blog

Komplexe Geschäftslogik als ein Modell verwalten

•Alexandros Fotiadis
geschäftslogikdomänenmodellierungmcpclaude-codeopen-sourceappling
Komplexe Geschäftslogik als ein Modell verwalten

Komplexe Geschäftslogik bleibt beherrschbar, wenn sie an einem Ort steht, den eine Maschine prüfen kann. Schreiben Sie die Regeln einmal als Modell auf: was es gibt, was passieren kann, wer es darf. Jedes Diagramm entsteht dann aus diesem Modell, und jede Frage zur Logik geht zuerst an das Modell.

Dieser Beitrag zeigt das Vorgehen an einem kleinen Freigabeprozess für Rechnungen. Das Werkzeug ist Appling, eine Open-Source-Modellierungssprache, die wir sponsern und mit der wir unsere Anwendungen entwickeln. Sie ist noch früh (0.x), steht unter MIT-Lizenz und lässt sich für die folgenden Schritte bereits nutzen.

Warum Geschäftslogik außer Kontrolle gerät

Geschäftslogik steht selten in einer Datei. Das Statusfeld liegt im Datenbankmodell, die Berechtigungsprüfung im Controller, die Frist in einem Cronjob und die Regel „diesen Button ausblenden“ im Frontend.

Jedes Stück ist für sich korrekt. Das Ganze sieht niemand.

Eine einfache Frage wie „Wer darf eine Rechnung freigeben, und aus welchem Status?“ heißt dann: vier Dateien lesen und zwei Kollegen fragen. Jede neue Funktion fügt einen fünften Ort hinzu.

flowchart LR
    subgraph Scattered["Logik verteilt im Code"]
      direction TB
      A1["models.py<br/>Statusfeld"]:::bad
      A2["views.py<br/>Berechtigung"]:::bad
      A3["cron.py<br/>Ablauf-Job"]:::bad
      A4["Invoice.tsx<br/>Button-Regel"]:::bad
    end
    subgraph One["Logik in einem Modell"]
      direction TB
      M["billing.appling"]:::good --> V["geprüft"]:::good
      M --> D["dargestellt"]:::good
      M --> Q["abgefragt"]:::good
    end
    Scattered --> One
    classDef good fill:#494fdf,stroke:#376cd5,color:#ffffff,stroke-width:2px
    classDef bad fill:#1e293b,stroke:#64748b,color:#f1f5f9,stroke-width:1.5px

Die Logik einmal als Modell beschreiben

Ein Modell der Geschäftslogik hält die Regeln fest, nicht die Umsetzung. Vier Fragen decken das meiste ab:

  1. Was gibt es? Entitäten, ihre Felder, die erlaubten Werte.
  2. Was kann passieren? Aktionen, Statuswechsel, geplante Jobs.
  3. Wer darf es? Rollen und Richtlinien.
  4. Wie erreicht man es? APIs und Seiten.

Appling ordnet das in fünf Schichten, von Domain (was es gibt) bis Experience (wie Menschen es erreichen). Verweise zeigen nur nach unten. Diese eine Regel verhindert, dass ein wachsendes Modell so verknotet wird wie der Code.

Das Modell ist reiner Text. Es liegt in Git, durchläuft Reviews und erzeugt Diffs wie Code.

Geschäftslogik aus dem Modell visualisieren

Ein Whiteboard-Diagramm ist am Tag nach dem Meeting veraltet. Ein Diagramm, das aus dem Modell entsteht, kann nicht abweichen, weil es jedes Mal aus demselben Text berechnet wird.

Das ist der Lebenszyklus einer Rechnung, den wir unten modellieren. Jeder Pfeil ist eine Aktion, und das Modell legt fest, wer sie ausführen darf:

flowchart LR
    draft -->|Submit<br/>Accountant| submitted
    submitted -->|Approve<br/>Manager| approved
    submitted -->|Reject<br/>Manager| rejected
    approved -->|MarkPaid<br/>Accountant| paid
    classDef state fill:#494fdf,stroke:#376cd5,color:#ffffff,stroke-width:2px
    class draft,submitted,approved,rejected,paid state

In Appling zeichnen Sie das nicht von Hand. Die IDE und das MCP-Fenster stellen es aus dem Modell dar.

Appling-IDE: links der Modelltext, in der Mitte die Modellansicht, vom Modul sales bis zur Entität Order und ihren Aktionen aufgeklappt, rechts der Inspektor

Die Ansicht wächst von den Modulen nach oben und klappt nur auf, was Sie anklicken: hier die Entität Order des Beispielmodells sales, dann die Aktionen, die auf ihr arbeiten. Jeder Klick markiert zugleich den Quelltext links.

Geschäftslogik nachvollziehbar halten

Observability zur Laufzeit (Logs, Metriken, Traces) zeigt, was passiert ist. Nachvollziehbare Logik zeigt, was passieren darf, bevor jemand den Code ausführt.

Mit einem Modell können Sie jederzeit fragen:

  • Kann eine Rechnung paid erreichen, und über welche Schritte?
  • Welche Rollen dürfen Approve auslösen?
  • Welche Regeln gefährdet eine Aktion?
  • Wo im Code ist diese Regel umgesetzt?

Die ersten drei Fragen beantwortet der Simulator von Appling, die vierte die Code-Referenzen: Datei und Zeilenbereich pro Element, die dem Code folgen, wenn sich Zeilen verschieben. Die Antworten kommen aus dem Modell und gelten daher für jede Umsetzung davon.

In der IDE stehen diese Antworten im Inspektor. Für eine Zustandsmaschine listet er jeden erreichbaren Status mit den Schritten dorthin:

Inspektor der Appling-IDE für die Zustandsmaschine OrderFlow mit den erreichbaren Status draft, placed, paid und cancelled und den Aktionen, die dorthin führen

Für eine Aktion zeigt er, was sie voraussetzt, was sie ändert, welchen Übergang sie auslöst und wo sie verwendet wird:

Inspektor der Appling-IDE für die Aktion PlaceOrder mit Vorbedingung, gesetztem Feld, dem Übergang von draft nach placed und dem ausgelösten Event

Das erste Appling-Modell schreiben

Sie brauchen Node.js 24 oder neuer. Die Einrichtung dauert etwa zehn Minuten. Die Installationsanleitung nennt die zusätzlichen Voraussetzungen für die Codegenerierung.

1. CLI installieren und den Modellordner anlegen.

Terminal window
npm install --save-dev @appling/cli
mkdir models

2. Die erste Modelldatei schreiben. Legen Sie models/billing.appling an:

module billing {
  role Accountant
  role Manager
  actor human Clerk roles Accountant
  actor human Director roles Manager


  enum InvoiceStatus {
    draft
    submitted
    approved
    rejected
    paid
  }


  entity Invoice {
    number: String unique
    amount: Money
    status: InvoiceStatus state default draft


    invariant "amount is positive" { amount > 0 }
  }


  action Submit on Invoice {
    requires { amount > 0 } else ZeroAmount
    errors ZeroAmount
    policy { actor.is(Accountant) }
  }


  action Approve on Invoice {
    policy { actor.is(Manager) }
  }


  action Reject on Invoice {
    input {
      reason: String
    }
    policy { actor.is(Manager) }
  }


  action MarkPaid on Invoice {
    policy { actor.is(Accountant) }
  }


  machine InvoiceFlow on Invoice.status {
    transition draft -> submitted via Submit
    transition submitted -> approved via Approve
    transition submitted -> rejected via Reject
    transition approved -> paid via MarkPaid
  }
}

Das Feld status ist als state markiert, also darf nur die Zustandsmaschine InvoiceFlow es ändern. Jede policy legt fest, wer die Aktion ausführen darf.

3. Prüfen.

Terminal window
npx appling check models
1 file(s), 0 error(s)

4. Absichtlich einen Fehler einbauen. Ändern Sie den letzten Übergang in approved -> settled und prüfen Sie erneut:

models/billing.appling:48:5 error "settled" is not a value of InvoiceStatus.
1 file(s), 1 error(s)

Der Exit-Code ist 1, derselbe Befehl schützt also Ihre CI. Machen Sie die Änderung rückgängig.

5. Dem Modell Fragen stellen.

Terminal window
npx appling simulate reach billing.InvoiceFlow paid models
npx appling simulate actors billing.Approve models
paid is reachable from draft:
  Submit -> submitted
  Approve -> approved
  MarkPaid -> paid


billing.Clerk: no
billing.Director: yes

6. Die IDE öffnen.

Terminal window
npx @appling/ide models

Öffnen Sie http://127.0.0.1:4410. Der Text steht neben einer Karte des Modells, mit einer Suche über alle Elemente und einem Inspektor, der zu jeder Aktion zeigt, wer sie ausführen darf. Die IDE-Anleitung beschreibt jeden Bereich.

Wer erst ohne Installation schauen möchte, nutzt die Demo unten. Es ist dieselbe IDE mit dem Beispielmodell für Vertrieb und CRM, vollständig im Browser. Klicken Sie einen Kreis an, um ihn aufzuklappen, oder wählen Sie ein Element in der Suche.

Auf kleinen Bildschirmen öffnen Sie die Demo im Vollbild.

Den Appling-MCP-Server mit Claude Code verbinden

Der MCP-Server gibt Claude Code geprüften Zugriff auf das Modell. Claude liest es, fragt den Simulator und ändert es nur über Operationen, die das Modell gültig halten.

1. Das KI-Paket installieren.

Terminal window
npm install --save-dev @appling/ai

2. Den Server für den Modellordner registrieren.

Terminal window
claude mcp add appling -- npx appling-mcp models

3. In eigenen Worten nach der Logik fragen. Starten Sie Claude Code im Projekt und versuchen Sie:

Welche Rollen dürfen eine Rechnung freigeben, und aus welchem Status?

Claude antwortet über graph_query und simulate, nicht durch Raten in Quelldateien. Der Server teilt ihm mit, dass das Modell die maßgebliche Quelle für Geschäftsregeln ist. Dasselbe Prinzip steht hinter unserem Beitrag zum eigenen MCP-Server für Claude Code: Ein typisiertes Tool schlägt jedes Raten des Modells.

4. Die Logik ändern. Bitten Sie um eine Änderung, etwa „ein Manager soll eine abgelehnte Rechnung zurück in den Entwurf schicken können“. Claude nutzt dafür das Tool edit. Eine Änderung, die einen Fehler einführen würde, wird mit Begründung abgelehnt, und die Datei bleibt unverändert.

sequenceDiagram
    participant Sie
    participant CC as Claude Code
    participant MCP as appling-mcp
    participant M as models/*.appling
    Sie->>CC: "Wer darf eine Rechnung freigeben?"
    CC->>MCP: simulate actors billing.Approve
    MCP->>M: lesen und prüfen
    MCP-->>CC: Clerk: no, Director: yes
    CC-->>Sie: Nur die Rolle Manager, aus submitted

Das MCP-Visualisierungsfenster nutzen

Über stdio kann der Appling-MCP-Server ein kleines Visualisierungsfenster neben Ihrem Terminal öffnen und das Modell dort darstellen. Sie sprechen weiter mit Claude Code; das Fenster zeigt, worüber Sie sprechen.

1. Eine Ansicht anfordern.

Zeig mir den Lebenszyklus einer Rechnung.

Claude ruft visualize auf. Ein rahmenloses Fenster öffnet sich oben rechts auf dem Bildschirm, über allen anderen Fenstern, ohne dem Terminal den Fokus zu nehmen. Die Ansicht machine zeigt eine Karte pro Status mit dem, was dort möglich ist. Weitere Ansichten zeigen Entitäten, einzelne Aktionen, Use Cases und Events.

2. Auf etwas zeigen. Klicken Sie eine Karte oder Zeile an und schreiben Sie im Terminal „erklär mir das“. Claude liest Ihre Auswahl mit visual_selection.

3. Änderungen im Fenster prüfen. Solange das Fenster offen ist, schlägt Claude Änderungen am Modell mit propose_edits vor. Das Fenster zeigt die Zusammenfassung und die geänderten Zeilen. Accept schreibt sie in die Dateien; Reject lässt die Dateien unverändert und gibt Ihren Kommentar an Claude zurück.

4. Optional: Fragen direkt ins Fenster tippen. Dort getippte Fragen erreichen die Sitzung über Claude-Code-Channels, eine Research Preview. Starten Sie Claude Code mit dem Namen des Servers:

Terminal window
claude --dangerously-load-development-channels server:appling

Das Fenster braucht @appling/ai 0.1.2 oder neuer. Es läuft auf Electron und lädt die Binärdatei beim ersten Start herunter. Unter Linux mit Wayland läuft es über XWayland, das GNOME und KDE mitbringen.

Mit dem Modell beginnen, nicht mit dem Code

Die Kernaussage: Komplexe Geschäftslogik wird beherrschbar, sobald sie einen Ort hat, den eine Maschine prüft, darstellt und befragen lässt. Code, Diagramme und KI-Änderungen folgen dann dem Modell, statt jeweils eine eigene Fassung der Regeln zu führen.

Beginnen Sie mit einem Ablauf, der heute schmerzt, etwa Freigaben oder Bestellstatus, und modellieren Sie nur diesen. Die Appling-Dokumentation beschreibt die ganze Sprache, ein zehnminütiges Tutorial zum ersten Modell, das Ableiten eines Modells aus bestehendem Code mit Claude Code und die Codegenerierung für Django, Ash, Go und Rust. Der Quellcode liegt auf GitHub.

Wenn Sie Unterstützung beim Modellieren eines verworrenen Prozesses in Ihrem System möchten, sprechen Sie mit uns.