DEV.2.2 — Dokumentation der (Software-)Architektur

Entwicklung für Anwendungen SOLLTE die Architektur dokumentieren.

Die Architektur bezeichnet im konkreten Kontext die strukturierte Beschreibung der grundlegenden Komponenten einer Software sowie deren Schnittstellen, Abhängigkeiten und das Datenmodell. Sie stellt dar, wie Module, Datenflüsse und externe Systeme ineinandergreifen, und bildet damit das Gerüst für Wartung, Weiterentwicklung und Sicherheitsbewertungen. Ohne dokumentierte Architektur könnte eine Institution nach Jahren vor der Situation stehen, dass nur einzelne Entwickler den Aufbau verstehen, was den Wissenstransfer erschwert und bei Personalwechseln erhebliche Risiken birgt. Eine unklare oder fehlende Dokumentation könnte zudem dazu führen, dass Abhängigkeiten von proprietären Technologien übersehen werden, wodurch sich ein Vendor Lock-in entwickelt, der die Institution langfristig bindet. Umgekehrt kann eine nachvollziehbare Architektur Dokumentation sicherstellen, dass Schwachstellenanalysen effizient durchgeführt werden, dass Sicherheitslücken frühzeitig erkannt werden und dass neue Entwickler schneller eingearbeitet werden können. Zur Umsetzung der Anforderung kann eine Institution standardisierte Diagrammtypen wie UML oder C4 einsetzen, um Abhängigkeiten und Schnittstellen verständlich abzubilden. Hilfreich kann es sein, die Architektur in mehreren Sichten zu dokumentieren, etwa eine logische Sicht (Funktionen und Module), eine technologische Sicht (Server, Container, Frameworks) und eine sicherheitsrelevante Sicht (z. B. Trust Boundaries). Die Dokumentation kann in Versionskontrollsystemen wie Git gepflegt werden, sodass Änderungen an Architekturentscheidungen nachvollziehbar bleiben. Ergänzend kann es praktikabel sein, automatisierte Werkzeuge einzusetzen, die Code-Strukturen analysieren und Diagramme generieren, wodurch Konsistenz zwischen Dokumentation und Implementierung unterstützt werden kann.

{
  "class": "BSI-Stand-der-Technik-Kernel",
  "id": "DEV.2.2",
  "parts": [
    {
      "id": "DEV.2.2_stm",
      "name": "statement",
      "props": [
        {
          "name": "target_object_categories",
          "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/target_object_categories.csv",
          "value": "Anwendungen"
        },
        {
          "name": "documentation",
          "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/documentation_guidelines.csv",
          "value": "Entwicklungsdokumentation"
        },
        {
          "name": "result",
          "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/result.csv",
          "value": "die Architektur"
        },
        {
          "name": "action_word",
          "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/action_words.csv",
          "value": "dokumentieren"
        },
        {
          "name": "modal_verb",
          "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/modal_verbs.csv",
          "value": "SOLLTE"
        }
      ],
      "prose": "Entwicklung für Anwendungen SOLLTE die Architektur dokumentieren."
    },
    {
      "id": "DEV.2.2_gdn",
      "name": "guidance",
      "prose": "Die Architektur bezeichnet im konkreten Kontext die strukturierte Beschreibung der grundlegenden Komponenten einer Software sowie deren Schnittstellen, Abhängigkeiten und das Datenmodell. Sie stellt dar, wie Module, Datenflüsse und externe Systeme ineinandergreifen, und bildet damit das Gerüst für Wartung, Weiterentwicklung und Sicherheitsbewertungen. Ohne dokumentierte Architektur könnte eine Institution nach Jahren vor der Situation stehen, dass nur einzelne Entwickler den Aufbau verstehen, was den Wissenstransfer erschwert und bei Personalwechseln erhebliche Risiken birgt. Eine unklare oder fehlende Dokumentation könnte zudem dazu führen, dass Abhängigkeiten von proprietären Technologien übersehen werden, wodurch sich ein Vendor Lock-in entwickelt, der die Institution langfristig bindet. Umgekehrt kann eine nachvollziehbare Architektur Dokumentation sicherstellen, dass Schwachstellenanalysen effizient durchgeführt werden, dass Sicherheitslücken frühzeitig erkannt werden und dass neue Entwickler schneller eingearbeitet werden können. Zur Umsetzung der Anforderung kann eine Institution standardisierte Diagrammtypen wie UML oder C4 einsetzen, um Abhängigkeiten und Schnittstellen verständlich abzubilden. Hilfreich kann es sein, die Architektur in mehreren Sichten zu dokumentieren, etwa eine logische Sicht (Funktionen und Module), eine technologische Sicht (Server, Container, Frameworks) und eine sicherheitsrelevante Sicht (z. B. Trust Boundaries). Die Dokumentation kann in Versionskontrollsystemen wie Git gepflegt werden, sodass Änderungen an Architekturentscheidungen nachvollziehbar bleiben. Ergänzend kann es praktikabel sein, automatisierte Werkzeuge einzusetzen, die Code-Strukturen analysieren und Diagramme generieren, wodurch Konsistenz zwischen Dokumentation und Implementierung unterstützt werden kann."
    }
  ],
  "props": [
    {
      "name": "alt-identifier",
      "value": "79eb639b-25ed-4ce3-9d8f-c57b573c1ee3"
    },
    {
      "name": "sec_level",
      "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/security_level.csv",
      "value": "normal-SdT"
    },
    {
      "name": "effort_level",
      "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/effort_level.csv",
      "value": "3"
    },
    {
      "name": "tags",
      "ns": "https://github.com/BSI-Bund/Stand-der-Technik-Bibliothek/tree/main/Dokumentation/namespaces/tags.csv",
      "value": "Security by Design"
    }
  ],
  "title": "Dokumentation der (Software-)Architektur"
}