Am Anfang einer jeden Entwicklung steht ein durchdachter Architekturentwurf – jedoch werden oft schon nach kurzer Zeit aufgrund neuer Erkenntnisse und Anforderungen davon abweichende Strukturen implementiert. Damit ist der ursprüngliche Entwurf veraltet, das entsprechende Architekturdokument verliert an Bedeutung und die Software-Architektur lebt von diesem Zeitpunkt an hauptsächlich auf Codeebene. Übrig bleibt allzu häufig eine wuchernde Software-Architektur, die schwer zu managen und zu warten ist.

Erkennen von architektonischen Strukturen aus Code

Die berechtigte Frage ist nun: Warum werden Architektur- dokumente nicht fortlaufend aktualisiert? Viele Teams leben anstelle eines Top-down „Architekturentwurf -> Codeerzeugung“-Prozesses eine Bottom-up-Vorgehensweise nach dem Motto „die Architektur entwickelt sich im Wesentlichen bei der Umsetzung“. So ist eine einfache Antwort auf die Frage: Es ist mühsam nachträglich Dokumente zu pflegen und zu aktualisieren. Doch mit den Möglichkeiten der generativen KI steht nun ein praktikabler Steigbügel zur Verfügung. Mit vergleichsweise geringem Aufwand lässt sich ein guter Überblick über die Architektur auf Codeebene, aber auch im Sinne einer Zusammenfassung höhere Abstraktionsebenen extrahieren und generieren. Damit wird ein fließender Austausch zwischen dem vorwärts gerichteten Entwurf und einer rückwärts gerichteten Architekturdokumentation möglich. Das Resultat sind lebende Architekturdokumente, die ihrem richtungsweisenden und dokumentierenden Anspruch gerecht werden.

Diese Aspekte werden anhand eines Anwendungsbeispiels mit einer frei zugänglichen Code-Basis beleuchtet. Aus der Code-Basis des Open-Source-Tools ‚Chainlit‘ werden dazu folgende drei Abstraktionsebenen gemäß der C4-Methode zur Architekturdokumentation extrahiert:

• System und Kontext Ebene
• Container Ebene
• Komponenten Ebene
   

Der wiederverwendbare Prompt zur Architekturdokumentation

Bild 4. Automatisiert extrahierte C4 Komponentendarstellung des Chainlit Backends.

© talsen team

Wie auch in den vorherigen Artikeln sind die Prompt-Techniken „vom Groben zum Feinen“ ein zentraler Handlungsleitfaden. Auch die Architekturdokumentation ist ein wiederkehrender Prozess. Es lohnt sich also von vorherein einen wiederverwendbaren Prompt für diese Aufgabe zu erstellen, zu versionieren und wiederholt einzusetzen. Anhand dieses Beispiels wird sichtbar, dass Prompts nicht nur für den schnellen Chat verwendbar sind, sondern, dass der weitaus größere Wert in der Automatisierung liegt. Ein guter Vergleich könnte vielleicht mit Skripten zur Infrastruktur gezogen werden. Ein guter Prompt ist quasi ein „Skript“ und sollte somit wie Code behandelt werden; genauso wie das Ergebnis des Prompts. Es ist durch die Natur der LLMs bedingt, dass unterschiedliche Durchläufe derselben Anfrage verschiedene Antworten und Fehler erzeugen. Somit ist es in der praktischen Anwendung entscheidend, die Ergebnisse sofort zu versionieren, dann grundlegend zu prüfen und gegebenenfalls zu korrigieren und eine neue Version des überarbeiteten Ergebnisses zu erstellen. Von diesem Zeitpunkt an ist es möglich, sich nur noch auf die Veränderungen zu konzentrieren. Diese sind dann entweder aus der Code-Basis selbst (erwünscht) oder zufällige Artefakte der LLMs (unerwünscht) und können sofort verworfen werden.

Die in Bild 1 dargestellte Struktur von Prompts hat sich für diese Aufgabenart bewährt. So sind einerseits wiederkehrende Anteile aus vorformulierten Templates einfach nutzbar und andererseits wird ein ausreichender Freiraum für den spezifischen Prompt der jeweiligen spezifischen Aufgabe gelassen. In unserem konkreten Beispiel zur Architekturdokumentation sind:

• Rules: Template für die wichtigsten Regeln für einen Softwarearchitekten mit C4-Methodenwissen
• Givens: variabler, gegebener Kontext bestehend aus den Quelldateien der Backend-Komponente des Open Source Tools Chainlit (~6500 Zeilen, beim Nachstellen auf ein geeignetes ausreichend großes Kontext-Window der LLM achten)
• Intention: unsere konkrete variable Handlungsanweisung zur Erstellung eines spezifischen Diagramms als Architekturdokumentation
• Commands: Template einer Anweisungsliste, wie ein konkretes C4 Diagramm zu erstellen, inklusive eines konkreten Beispiels und der Definition des Zielformats der KI-Antwort

Zum Nachstellen und für eigene Experimente sind unsere Prompt-Bausteine konkret wie folgt formuliert:

1) Rules:
### RULES OF AN EXPERT ARCHITECTURE REVERSE ENGINEERING ANALYST

1. Serve as a proficient architecture reverse engineering analyst with deep expertise in code patterns, SOLID design principles, and the C4 method for architecture documentation.
2. Identify and articulate key architectural components, their responsibilities, and interactions within the system.
3. Apply the C4 method rigorously to create clear, structured, and layered architecture documentation, including Context, Container, Component, and Code diagrams.
4. Apply the principles of reverse engineering to reconstruct high-level architectural views from the existing code and documentation.

You are expert in applying the rules of the for different C4 Diagram types for architecture documentation which are as follows:

1. **C4 System Context Diagram**
               Specific description of diagram type comes here …                                       2. **C4 Container Diagram**                                                                                                           Specific description of diagram type comes here …                                         3. **C4 Component Diagram**
               Specific description of diagram type comes here …                                       4. **C4 Code Diagram**
               Specific description of diagram type comes here …

2) Givens (Auflistung des gesamten Backend Codes mit ca. ~6500 Zeilen und ~190.000 Zeichen)

### GIVENS
chainlit-main/backend/chainlit/__init__.py
```
Code comes her …
```
chainlit-main/backend/chainlit/__main__.py
```
Code comes her …
```
Plus alle weiteren Dateien aus der vollständigen Backend-Komponente von Chainlit.

3) Intention (Handlungsabsicht)
Zur Architekturdokumentation benötigt man gemäß der Abstraktionsebenen mindestens vier unterschiedliche Handlungsabsichten. Diese sind wie folgt als Baustein für jeweils einen Gesamtprompt pro Abstraktionsebene und Architekturdokumentationsaufgabe formuliert. Für unterschiedliche Schwerpunkte in der Architekturdokumentation findet die Prompt-Anpassung ausschließlich in diesem Prompt-Baustein statt. Die restlichen drei Prompt-Bausteine können unverändert bleiben, was trotz der Länge des Prompts eine schnelle Prompt-Erstellung bedeutet.Hier die in diesem Beispiel verwendeten Prompts inkl. der extrahierten und visualisierten Ergebnisse.

### INTENTION (C4 System and Context diagram)
Prompt:“my intention is to generate a very detailed „C4 System Context diagram“ using the given code base of the application. In order to reach the intended level of detail you need to extract detailed information of each given source file.“

Bewertung der LLM-Antwort: Wenn der Code wie in diesem Beispiel entweder auf einer von sich aus deskriptiven High-Level-Sprache wie hier Python oder alternativ auf Java oder C# beruht, werden die Inhalte und Strukturen in aller Regel gut wiedergegeben. Dies gilt auch für Code Basen in Low-Level-Sprachen wie C oder C++, die aber diszipliniert mit deskriptivem Bezeichner programmiert sind. Bei kryptisch implementiertem Code, der eventuell ohne einheitlichen Styleguide von unterschiedlichen Personen implementiert wurde, sind deutlich schlechtere Ergebnisse zu erwarten. Bei Code, dessen Abhängigkeiten in einem Projektierungswerkzeug vor den Augen der LLMs versteckt sind, wie das bei manchen IEC 61131-Werkzeugen der Fall sein kann, sind die KIs in dem hier beschriebenen Ansatz praktisch mittellos und es sind keine wirklich nützlichen Ergebnisse zu erwarten.

### INTENTION (C4 System and Container diagram)
Prompt: “my intention is to generate a very detailed „C4 Container diagram“ using the given code base of the application. In order to reach the intended level of detail you need to extract detailed information of each given source file.”

Bewertung der LLM-Antwort: Das Ergebnis ist in der Qualität mit dem vorangegangenen High-Level- Diagramm auf System und Kontext Ebene vergleichbar und erfasst und abstrahiert die Strukturen der Code-Basis erstaunlich gut.

### INTENTION (C4 System and Component diagram)
Prompt: “my intention is to generate a very detailed „C4 Component diagram“ using the given code base of the application. For the component diagram now zoom in on the „Container(web_app, „Web Application“, „FastAPI“, „Handles HTTP requests and serves the frontend“)“ described in the „chainlit_C4_container_Diagram.md“. In order to reach the intended level of detail you need to extract detailed information of each given source file.”

Bewertung der LLM-Antwort: Bei den vorausgegangenen Diagrammen wurden sehr hohe Abstraktionsebenen abgefragt, die die Zusammenfassung und Abstraktion eines großen Kontextes erfordern. Das gelingt gpt-4o als LLM sehr gut. Dabei kann allerdings nicht gleichzeitig die für die Komponentendarstellung gewünschte Detailtiefe erreicht werden. Dem entsprechend ist es wichtig, einen spezifischen Fokus zu setzen. Kann sich die LLM wieder auf einen speziellen Teilbereich der Code-Basis „konzentrieren“ sind die Ergebnisse erstaunlich gut und im Sinne einer schnellen rückwärtsgerichteten Architekturdokumentation sehr nützlich.

4) Anweisungsliste zur Extraktion und Generierung der C4 PlantUML Diagramme

Als letzter der vier Prompt-Bausteine ist nach der Handlungsabsicht das konkrete Kochrezept für die Abarbeitung des Prompts durch die LLM erforderlich. Für unsere Architekturextraktionsaufgabe ist dieses wie folgt formuliert.

### COMMANDS FOR EXPERT ARCHITECTURE REVERSE ENGINEERING ANALYST

Your job is now:

* Remember you are strictly following your given RULES and SKILLS AS AN EXPERT ARCHITECTURE REVERSE ENGINEERING ANALYST
* Silently analyse the intended architectural structure and behaviour of the entire given code base in detail and also analyse any further documentation in detail if given.
* Then generate based on your analysis the detailed architecture for the specified C4 diagram type. In case no specific diagram type is requested generate a „C4 System Context Diagram“ per default and inform the user about that default decision. Use the C4 PlantUML format template. Here is an example of how the PlantUML code could look like for a „System Context Diagram“:

```plantuml
@startuml
!define C4_Code
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

LAYOUT_WITH_LEGEND()

Person(user, „User“)
System(system, „Our System“, „Description“)
Rel(user, system, „Uses“)
@enduml
```

* then return your finally generated architectural diagram in the following format of a plantuml diagram embedded in a markdown document
```markdown
# [ ] extract
# filename: {path/filename}.{md}
{C4 plantuml diagram}
```
* In case you think information is missing to generate a sufficiently precise formulation, return a warning „WARNING: information is missing to correctly fulfil the job!“ and then explain what kind of information you think is missing and how it can be easily retrieved.
 

Fazit zur Architekturdokumentation mit LLMs

Der Autor: Dr. Hans Egermeier ist Geschäftsführer von talsen team.

© talsen team

Die Verwendung generativer KI-Methoden für die Architekturextraktion und Dokumentation ist von großem Nutzen. Ganz besonders, wenn die Code-Basis wohl strukturiert und mit sprechenden Bezeichnern und Operanden implementiert wurde. Dann ist die zu erwartende Qualität vor allem auch in Kombination mit der C4-Methode zur Beschreibung der gewünschten Abstraktionsebenen zur Architekturdokumentation erstaunlich hoch und auf jeden Fall einen praktischen Versuch wert. In unserem nächsten Beitrag werden wir die Fähigkeit von ChatGPT (gpt-4o) untersuchen, wie Software-Architekturen und Code nicht dokumentiert, sondern auch bewertet beziehungsweise Änderungsvorschläge erstellt werden können.