Architekturdokumentation

Wenn ein Projekt wächst, wird Code allein zu einer schwachen Erklärungs-Grundlage. Welche Bibliothek wurde aus welchem Grund gewählt? Warum leben zwei Features in getrennten Gradle-Modulen? Ohne festgehaltene Entscheidungen verliert das Team den roten Faden – besonders beim Onboarding neuer Entwickler oder nach längeren Abwesenheiten. Architekturdokumentation schließt diese Lücke, indem sie das Warum hinter dem Code explizit und nachvollziehbar macht.

Was ist das?

Architekturdokumentation ist die Gesamtheit aller Artefakte, die erklären, wie ein Software-System aufgebaut ist und warum es so aufgebaut wurde. In einem Android-Projekt deckt sie typischerweise drei Ebenen ab:

Moduldiagramme zeigen, welche Gradle-Module existieren und wie sie voneinander abhängen. Sie helfen dabei, unerwünschte Zyklen oder zu starke Kopplung auf einen Blick zu erkennen.

Datenfluss-Diagramme beschreiben, wie Daten von der Datenschicht über ViewModels bis zur UI fließen – etwa von einem Room-DAO durch einen Repository-Layer in einen StateFlow, den Composables per collectAsStateWithLifecycle() abonnieren.

Architecture Decision Records (ADRs) halten einzelne Architekturentscheidungen in einem kurzen, versionierten Textformat fest. Ein ADR erklärt nicht, was der Code tut, sondern warum er genau so strukturiert ist.

Die offizielle Android-Architekturanleitung empfiehlt eine klare Schichtentrennung in UI-, Domain- und Data-Layer. Doch welche konkreten Entscheidungen dein Team innerhalb dieses Rahmens getroffen hat – warum ihr Hilt statt Koin einsetzt, warum ein Feature ein eigenes Modul bekommen hat – geht aus dem Code allein nicht hervor. Genau das ist der Wert von Architekturdokumentation.

Wie funktioniert es?

Architecture Decision Records

Ein ADR ist eine Markdown-Datei, die im Projektrepository unter docs/adr/ abgelegt wird. Das Format ist bewusst kompakt:

• Titel und laufende Nummer, z. B. 0012-use-hilt-for-di.md
• Status: Proposed / Accepted / Superseded
• Kontext: Welche Anforderung oder welches Problem hat diese Entscheidung ausgelöst?
• Entscheidung: Was wurde beschlossen?
• Konsequenzen: Welche positiven und negativen Auswirkungen hat die Entscheidung?

Da die Dateien im Git-Repository versioniert sind, ist jeder ADR vollständig nachvollziehbar: Wann wurde die Entscheidung getroffen, wer hat sie committet, und wurde sie später durch eine neuere Entscheidung abgelöst?

Modul- und Datenfluss-Diagramme

Für Android-Projekte eignet sich Mermaid als leichtgewichtiges Diagramm-Format, da es direkt in Markdown eingebettet werden kann und von GitHub sowie GitLab nativ gerendert wird. Alternativ generiert das Gradle-Plugin module-graph automatisch eine Abhängigkeitsgrafik aus der tatsächlichen Build-Konfiguration – diese bleibt immer aktuell, weil sie direkt aus dem Code entsteht.

Ein typischer Datenfluss in einer Jetpack-App folgt dem Prinzip: UI → ViewModel → Repository → DataSource. Wenn dieser Fluss einmalig als Diagramm dokumentiert ist, erkennen neue Entwickler sofort, wo eine Änderung ansetzt, ohne den gesamten Code lesen zu müssen. Abweichungen von diesem Standardmuster – etwa ein Feature ohne eigene Domain-Schicht – werden durch die Dokumentation sichtbar und erklärbar.

In der Praxis

Angenommen, euer Team entscheidet sich für Hilt als Dependency-Injection-Framework. Ein zugehöriger ADR könnte so aussehen:

# 0004 – Hilt als Dependency-Injection-Framework

**Status:** Accepted
**Datum:** 2026-03-15

## Kontext

Das Projekt benötigt DI für ViewModels, Repositories und DataSources.
Koin und Hilt sind die gängigsten Optionen im Kotlin-Android-Ökosystem.

## Entscheidung

Wir verwenden Hilt, da es offiziell von Google unterstützt wird,
nahtlos mit Jetpack ViewModel und Navigation Compose integriert ist
und Compile-Time-Validierung bietet.

## Konsequenzen

- Compile-Time-Fehler statt Runtime-Fehler bei Konfigurationsfehlern
- Bessere IDE-Unterstützung durch Annotation Processing
  − Höhere initiale Boilerplate im Vergleich zu Koin

Dieses Format lässt sich sofort auf andere Entscheidungen anwenden: Wahl des Netzwerk-Layers (Retrofit vs. Ktor), Strategie für lokales Caching (Room vs. DataStore), oder die Entscheidung, ein großes Mono-Modul in Feature-Module aufzuteilen.

Typische Stolperfalle: Dokumentation, die veraltet

Die häufigste Falle ist, dass Architekturdokumentation nach dem initialen Schreiben nicht mehr gepflegt wird. Module werden umbenannt, Datenflüsse ändern sich mit neuen Jetpack-Versionen, doch die Diagramme bilden weiterhin die alte Struktur ab. Das Ergebnis ist schlimmer als gar keine Dokumentation: Neue Entwickler werden aktiv in die Irre geführt und vertrauen Beschreibungen, die der Realität längst nicht mehr entsprechen.

Die Lösung ist zweigeteilt. Erstens helfen automatisch aus dem Build-System generierte Diagramme dabei, die strukturellen Aspekte dauerhaft korrekt zu halten. Zweitens gehört das Aktualisieren relevanter ADRs und Datenfluss-Beschreibungen zur Definition of Done eines Feature-Branches – genauso selbstverständlich wie das Schreiben von Tests und das Durchführen eines Code Reviews.

Fazit

Architekturdokumentation ist keine einmalige Aufgabe, sondern ein kontinuierlicher Prozess, der parallel zum Code gepflegt wird. ADRs halten Entscheidungen für künftige Entwickler – und dich selbst in sechs Monaten – nachvollziehbar fest. Moduldiagramme und Datenfluss-Beschreibungen verkürzen die Einarbeitungszeit erheblich und reduzieren Missverständnisse bei Reviews. Schau dir jetzt dein aktuelles Projekt an: Welche Architekturentscheidungen existieren, die nirgendwo dokumentiert sind? Leg einen ersten ADR dafür an, skizziere den Datenfluss deines komplexesten Features als Mermaid-Diagramm, und überprüfe, ob das Ergebnis einem neuen Teammitglied ohne mündliche Erklärung verständlich wäre.