CIAO - Code In Architecture Out - Automated Software Architecture Documentation with Large Language Models

Titel: CIAO - Code In Architecture Out: Geautomatiseerde Software-Architectuurdocumentatie met Large Language Models

1. Het Probleem

Software-architectuurdocumentatie is essentieel voor het begrijpen, onderhouden en evolueren van systemen. In de praktijk is deze documentatie echter vaak afwezig, verouderd of inconsistent met de daadwerkelijke implementatie. Dit leidt tot "architecturale drift" (waarbij de implementatie afwijkt van het ontwerp), architecturale erosie en technische schuld.

Hoewel recente technieken op basis van Large Language Models (LLMs) kunnen worden gebruikt om documentatie te genereren uit code, richten deze zich meestal op lokale artefacten (zoals API-beschrijvingen of code-commentaar) in plaats van samenhangende, systeem-brede architecturale beschrijvingen. Er ontbreekt een gestructureerde aanpak om volledige architectuurdocumentatie direct uit GitHub-repositories te genereren die voldoet aan industriestandaarden.

2. Methodologie: Het CIAO-proces

De auteurs introduceren CIAO (Code In Architecture Out), een gestructureerd proces dat LLMs gebruikt om automatisch systeemniveau-architectuurdocumentatie te genereren. Het proces bestaat uit de volgende componenten:

• Het Template (Sjabloon):
  Het proces gebruikt een sjabloon dat is afgeleid van drie gevestigde standaarden:

  1. ISO/IEC/IEEE 42010: Voor het definiëren van systeemscope, stakeholder-bekommeringen en rationale.
  2. SEI Views & Beyond: Voor het scheiden van structurele, gedrags- en deployingsperspectieven.
  3. Het C4-model: Voor een hiërarchische structuur op vier niveaus: Context (L1), Containers (L2), Componenten (L3) en Code (L4).

  Het sjabloon omvat acht secties:

  1. Systeemoverzicht (System Overview)
  2. Architecturale Context (External environment, actors, APIs)
  3. Containers (Logische runtime-organisatie)
  4. Componenten (Interne logische structuur)
  5. Code-niveau (Mapping naar broncode-artefacten)
  6. Cross-Cutting Concerns (Beveiliging, logging, etc.)
  7. Kwaliteitsattributen en Rationale
  8. Deployments (Infrastructuur en runtime-omgeving)

• De Workflow:

  1. Repository Flattening: De GitHub-repository wordt omgezet in één tekstueel bestand met behulp van REPOMIX. Hierbij worden niet-broncode-bestanden (zoals binaries) verwijderd, maar configuratiebestanden (Dockerfile, package.json) behouden.
  2. Prompt Generatie: Voor elke van de acht secties wordt een specifieke prompt samengesteld. Deze bevat een globaal deel (roldefinitie als "Meticulous Software Architect", schrijfstijl) en een sectie-specifiek deel gebaseerd op het sjabloon. De "geflattende" repository wordt aan elke prompt toegevoegd als context.
  3. LLM-Generatie: De prompts worden parallel verzonden naar het LLM (in dit geval GPT-5, geselecteerd na een pilot-studie vanwege de hoogste nauwkeurigheid en consistentie).
  4. Samenstelling en Rendering: De gegenereerde secties worden samengevoegd tot een tussenresultaat. Tekstuele PlantUML-diagrammen worden vervolgens omgezet naar visuele afbeeldingen.
  5. Output: Het resultaat is een compleet architectuurdocument (bijv. een README) dat direct in de repository kan worden geïntegreerd.

3. Belangrijkste Bijdragen

1. Een standaarden-georiënteerd sjabloon: Een gestructureerde template voor systeemniveau-documentatie die ISO 42010, SEI Views & Beyond en het C4-model integreert.
2. Een gestructureerde LLM-workflow: Een geautomatiseerd proces dat direct van GitHub-repositories naar volledige architectuurdocumentatie gaat, zonder handmatige tussenkomst.
3. Een open-source prototype: Een implementatie van de workflow die direct bruikbare documentatie genereert.
4. Empirische validatie: Een uitgebreide studie met 22 ontwikkelaars die de gegenereerde documentatie voor hun eigen repositories hebben beoordeeld.

4. Resultaten van de Evaluatie

De studie omvatte 22 ontwikkelaars (onderzoekers en professionals) die repositories van verschillende grootte en technologieën (Python, Java, C++, JS, etc.) analyseerden. De resultaten zijn als volgt:

• Waarde (RQ1): Ontwikkelaars vonden de documentatie over het algemeen waardevol voor het begrijpen van de systeemstructuur. Diagrammen en de "Componenten"-sectie werden het meest gewaardeerd.
• Begrijpelijkheid (RQ2): De documentatie werd als duidelijk en goed gestructureerd ervaren. De terminologie was consistent en passend.
• Nauwkeurigheid (RQ3):
  • Secties die direct gekoppeld zijn aan code (Containers, Componenten, Code-niveau) werden als zeer accuraat beoordeeld.
  • Hogere niveaus van abstractie (Systeemoverzicht, Use Case Diagrammen) en deployingsdiagrammen kregen gemengdere beoordelingen en bevatten vaker onnauwkeurigheden.
• Beperkingen (RQ4): De belangrijkste kritiekpunten waren:
  • Diagramfouten: Diagrammen waren vaak incompleet, onduidelijk of bevatten hallucinaties.
  • Deployingsproblemen: Onduidelijke relaties in de infrastructuurweergave.
  • Ontbrekende informatie: Soms werden specifieke details over componenten of gebruiksgeschiedenis gemist.
• Kosten en Efficiëntie (RQ5):
  • Tijd: Het genereren van een volledig document duurde gemiddeld 3 minuten.
  • Kosten: De API-kosten bedroegen gemiddeld $1,19 per repository. Dit maakt het proces zeer kosteneffectief vergeleken met handmatige documentatie.

5. Betekenis en Conclusie

Het paper toont aan dat een gestructureerde, standaarden-georiënteerde aanpak LLMs effectief kan sturen bij het produceren van systeemniveau-architectuurdocumentatie. Hoewel er nog uitdagingen zijn bij het genereren van visuele diagrammen en het modelleren van hoge context, biedt CIAO een kosteneffectieve en snelle oplossing om de kloof tussen code en architectuurdocumentatie te dichten.

De studie suggereert dat gegenereerde documentatie een bruikbare basis vormt voor ontwikkelaars, vooral voor onboarding en het begrijpen van complexe systemen, mits er een menselijke review plaatsvindt voor de visuele en deployingsaspecten. Toekomstig werk richt zich op het verbeteren van de diagramkwaliteit door statische analyse te integreren en het uitbreiden van de evaluatie naar industriële contexten.