Netzwerksolution Documentation Report

DEVELOPMENT-GUIDELINES

DEVELOPMENT_GUIDELINES.md#

Development Guidelines – Netzwerksolution#

Diese Richtlinien gelten für sämtliche Änderungen an der Netzwerksolution.

Ziel ist eine langfristig wartbare, testbare und nachvollziehbare Softwarearchitektur. Neue Funktionen sollen sich in die bestehende Architektur einfügen und nicht parallel dazu entstehen.

Die Datei ist bewusst als praktischer Entwicklungsleitfaden gehalten. Sie ersetzt kein großes Architekturhandbuch, sondern beschreibt verbindliche Regeln für die tägliche inkrementelle Weiterentwicklung.

Verbindlicher KI-Entwicklungsworkflow#

Für KI-gestützte Änderungen gilt zusätzlich verbindlich:

90-governance/guidelines/ENGINEERING_CHANGE_WORKFLOW.md

Dieses Dokument ist die Single Source of Truth für Roundtrip, Changed-only-Rückgabe, Import, Export, Statusmodell, lokale Toolchain und Teststrategie. Workspace und Building Blocks dürfen diese Regeln nur konkretisieren, nicht duplizieren oder abweichend definieren.

Verbindlicher Import- und Löschvertrag#

Für jede Änderung, die Dateien hinzufügt, überschreibt, entfernt oder als ZIP/Patch zurückgibt, gilt zusätzlich verbindlich:

90-governance/guidelines/ARTIFACT_IMPORT_AND_DELETE_RULES.md

Insbesondere gilt: Ein Changed-only-, Workspace-, SolutionArchitecture- oder Building-Block-ZIP ist kein impliziter Mirror. Dateien dürfen nur gelöscht werden, wenn sie im Manifest unter deletedFiles einzeln aufgeführt sind. Verzeichnisse, Wildcards und implizite Löschungen sind nicht zulässig.

Building-Block-Readiness-Promotion#

Ein leer vorbereiteter darf nur dann durch den Watcher promoviert werden, wenn er als Readiness-Artefakt ausdrücklich validiert ist. Dafür muss der Lifecycle-Record vollständig sein und die vom Promotion-Lifecycle geprüften Felder enthalten: lifecycle_state, maturity, promotion_allowed, last_validation.result und last_validation.timestamp.

Ein Readiness-Artefakt mit promotion_allowed=true bedeutet ausschließlich: Das leere Zielartefakt darf in Workspace und Building-Block-Repository aufgenommen werden. Es bedeutet nicht, dass die fachliche Implementierung abgeschlossen ist. Die spätere fachliche Migration benötigt erneut eigene Validierung, Tests und Lifecycle-Aktualisierung.

Runtime-neutrale Readiness-Building-Blocks dürfen keine Monolith- oder Runtime-Dateien überschreiben. Ihre integration-map.json muss auf ein leeres Assembly-Verzeichnis oder eine anderweitig belegbar neutrale Quelle zeigen.

Bootstrap- und Lifecycle-Kompatibilität#

Ein leerer Building Block muss unmittelbar nach dem Bootstrap alle strukturellen Schema-Anforderungen erfüllen. Wird er zusätzlich als Readiness-Artefakt für eine vorbereitet, muss sein lifecycle-record.json die vom Promotion-Lifecycle geprüften Pflichtfelder vollständig enthalten. Mindestens erforderlich sind:

Ein Bootstrap darf keine Artefakte erzeugen, die vom Download-Watcher aufgrund fehlender Pflichtfelder erst am Ende eines vollständigen Build- und Testlaufs zurückgewiesen werden. Lifecycle- und Schemafehler sind Import- oder Frühvalidierungsfehler.

Ein leerer Readiness-Building-Block darf keine Monolith- oder Runtime-Dateien in die Zielruntime kopieren oder überschreiben. Seine integration-map.json muss runtime-neutral sein, zum Beispiel durch ein belegbar leeres Assembly-Verzeichnis oder eine ausdrücklich dokumentierte No-op-Integration.

1. Grundprinzipien#

Vor jeder Änderung ist zu prüfen:

Neue globale Funktionen, Events oder Hilfsklassen werden nur eingeführt, wenn sie mehrfach benötigt werden.

Code wird für Menschen geschrieben.

Lesbarkeit besitzt Vorrang vor Mikrooptimierungen.

Eine schnelle Lösung darf keine Parallelarchitektur erzeugen. Falls eine kurzfristige Lösung gegen diese Richtlinien verstößt, wird dies vor der Umsetzung benannt.

2. Projektstruktur#

Alle Fachlogik ist in Features organisiert.

Beispiel:

features/
                    boards/
                    explorer/
                    ribbon/
                    sidepanel/
                    relationships/
                    universes/
                    systems/
                    capabilities/
                    usecases/
                    processes/

Jedes Feature besitzt klar abgegrenzte Verantwortlichkeiten.

Innerhalb eines Features werden Komponenten möglichst klein gehalten.

Beispiel:

relationships/

                    relationship-editor.js
                    relationship-renderer.js
                    relationship-routing.js
                    relationship-toolbar.js

Neue Dateien werden nur dort angelegt, wo sie fachlich hingehören.

Es werden keine zweiten Strukturen für dieselbe Fachlichkeit aufgebaut.

2a. Dokumentationsmodell#

Die Dokumentation unterscheidet verbindlich zwischen Solution Architecture und Solution Design.

Solution Architecture beschreibt ausschließlich globale Architektur, Architekturprinzipien, Building-Block-Konzept, Enterprise-Architecture, Prozesse, Standards, Packaging, Build-Strategie, Integrationsregeln, Release-Vorgehen und das Zusammenspiel aller Building Blocks.

Solution Design beschreibt ausschließlich die eigene Lösung eines Building Blocks: Verantwortung, Schnittstellen, Konfiguration, Implementierung, Tests, Deployment-Besonderheiten und interne Entscheidungen.

Der Workspace enthält keine Kopien der Building-Block-Dokumentation. Er beschreibt Runtime, Build, Deployment, Packaging, Installationsabläufe, Skripte und Entwicklungsumgebung.

Für Building-Block-Repositories ist die Dokumentationsstruktur verbindlich in 40-concepts/documentation-architecture/Building_Block_Documentation_Structure.md definiert. Dauerhafte Building-Block-Dokumentation liegt unter documentation/. Zeitlich gebundene Arbeitsunterlagen liegen unter working-documents/. documents/ ist eine Legacy-Struktur und darf in neuen oder normalisierten Building Blocks nicht mehr verwendet werden.

Workspace-Dokumente dürfen diese Regel nur umsetzen oder darauf verweisen. Die Sollstruktur eines Building Blocks wird nicht aus dem Workspace abgeleitet.

Historische Projektdokumente werden Plateau-bezogen abgelegt. Aktuelle Arbeitsanweisungen dürfen keine veralteten Paket- oder Arbeitsanweisungsreferenzen enthalten. Verweise auf früheres Monolith-Paket sind nur zulässig, wenn konkret dieses Building-Block-Paket gemeint ist; Verweise auf SolutionArchitecture.zip sind zulässig, wenn das globale Solution-Architecture-Paket gemeint ist.

2b. Modularisierung in zwei Phasen#

Building-Block-Splits werden nicht mehr automatisch als kombinierte Architektur- und Code-Sprints verstanden. Wenn Roadmap, Registry, Lifecycle, Packaging, Watcher oder Readiness vorab geklärt werden müssen, ist zuerst ein Architecture-and-Roadmap-Sprint durchzuführen.

Die verbindliche Regel steht in:

70-building-blocks/split-reports/BUILDING_BLOCK_SPLIT_PHASE_MODEL.md

Ein Migration-Sprint darf keine Roadmap-Widersprüche durch Annahmen auflösen. Er muss Roadmap, building-blocks.yaml, vorhandene Building-Block-ZIPs und Lifecycle-Records gegeneinander prüfen. Ist ein Building Block bereits in Registry oder building-blocks.yaml mit Extracted, Validated oder höher enthalten, darf er nicht erneut migriert werden, ohne dass die Architektur zuvor korrigiert oder der Widerspruch ausdrücklich aufgelöst wurde.

Komplexe oder unklare Splits erhalten vor der Migration einen Split-Plan unter:

20-building-blocks/plans/<BB-ID>_SPLIT_PLAN.md

Der Migration-Sprint arbeitet diesen Plan ab und dokumentiert jede Abweichung im Split-Report.

3. Komponenten#

Jede Komponente besitzt genau eine Aufgabe.

Komponenten sollen:

sein.

Große Dateien sind frühzeitig aufzuteilen.

Eine Komponente darf nicht direkt in interne Zustände anderer Komponenten greifen.

Kommunikation erfolgt über öffentliche APIs, definierte Events oder zentrale Controller.

4. HTML#

HTML wird grundsätzlich human readable geschrieben.

Regeln:

Beispiel:

<button
                    id="RelationshipsEditorDelete"
                    class="toolbar-button"
                    title="{{t.relationships.editor.deleteTooltip}}"
                >
                    {{t.relationships.editor.delete}}
                </button>

HTML wird so geschrieben, dass es in den Browser Developer Tools lesbar und nachvollziehbar bleibt.

5. IDs#

Alle interaktiven UI-Elemente besitzen eindeutige IDs.

Dies betrifft insbesondere:

IDs sind sprechend.

Beispiele:

RelationshipsEditorTitle

                RelationshipsEditorDescription

                RelationshipsEditorDirection

                RelationshipsEditorDelete

                UniverseCreateDialog

                BoardsZoomIn

                BoardsZoomOut

                ExplorerUniverseTree

Nicht zulässig:

button1

                input2

                editor001

IDs dienen für:

Separate data-testid-Attribute werden grundsätzlich nicht verwendet.

Es existiert genau eine eindeutige Identität eines UI-Elements.

Wichtig: Fachlogik soll nicht unnötig an DOM-IDs gekoppelt werden. JavaScript arbeitet bevorzugt über öffentliche Komponenten-APIs. Direkte DOM-Zugriffe bleiben auf Präsentationslogik, Initialisierung und Tests beschränkt.

6. CSS#

CSS beschreibt ausschließlich Darstellung.

Klassen dienen Layout und Styling.

IDs beschreiben eindeutige Elemente.

JavaScript selektiert nur dann über IDs, wenn es sich um Präsentationslogik handelt. Fachliche Abläufe laufen über Komponenten-APIs.

CSS-Klassen dürfen keine fachliche tragen, auf die Geschäftslogik angewiesen ist.

7. JavaScript#

Keine Inline-Handler.

Keine globale Fachlogik.

Globale Objekte dienen ausschließlich als Einstiegspunkt eines Features.

Komponenten kommunizieren über definierte APIs.

Funktionen und Module verwenden sprechende Namen.

Konventionen:

Dateien:
                    kebab-case.js
                    relationship-editor.js

                Funktionen:
                    camelCase
                    createRelationship
                    renderUniverseBoard

                Konstanten:
                    UPPER_SNAKE_CASE
                    DEFAULT_BOARD_ZOOM

                Events:
                    ns:<feature>-<aktion>
                    ns:board-selected
                    ns:relationships-changed

Neue öffentliche APIs werden dokumentiert.

8. Events#

Events werden sparsam eingesetzt.

Jedes Event besitzt:

Event-Ketten sollen nachvollziehbar bleiben.

Events ersetzen keine Programmlogik.

Ein Event darf nicht versteckt mehrere fachliche Aktionen auslösen, die im Code nicht nachvollziehbar sind.

Beispiel:

Event:
                    ns:board-selected

                Auslöser:
                    Benutzer oder Orchestrator wählt ein Board aus.

                Payload:
                    boardId
                    boardType
                    universeId

9. Tests#

Jede Komponente besitzt mindestens einen automatisierten Test.

Beispiele:

relationship-editor.test.js

                board-renderer.test.js

                explorer-tree.test.js

Komponententests prüfen die Komponente isoliert.

Sie prüfen keine fachlichen Roundtrips über mehrere Features hinweg. Dafür sind E2E-Tests zuständig.

10. End-to-End-Tests#

Jedes Feature besitzt mindestens einen End-to-End-Test.

Beispiele:

01-roundtrip.spec.ts

                relationships.spec.ts

                boards.spec.ts

                universes.spec.ts

Alle E2E-Tests erzeugen ihre Testdaten selbst.

Seed-Daten werden niemals vorausgesetzt.

Ein E2E-Test prüft fachliche Abläufe aus Sicht eines Benutzers.

Deaktivierte Features werden ebenfalls getestet. Ein Feature muss mindestens in diesen Varianten geprüft werden:

10.1 Testarchitektur und Erweiterbarkeit#

Die E2E-Tests sind Teil der Softwarearchitektur und halten dieselben Architekturprinzipien ein wie der Produktcode.

10.1.1 Bestehende Strukturen erweitern#

Bestehende Strukturen sind grundsätzlich zu erweitern. Neue Dateien, Komponenten, Module oder Testgruppen dürfen nur entstehen, wenn nachgewiesen wurde, dass die vorhandene Struktur fachlich nicht geeignet ist. Dieser Grundsatz gilt gleichermaßen für Produktcode und Tests.

Neue Funktionalität wird grundsätzlich in bestehende fachliche Testgruppen integriert. Neue Testdateien oder neue Test-Obergruppen dürfen nur entstehen, wenn ein neuer fachlicher Themenbereich eingeführt wird. Bestehende test.describe(...)-Gruppen sind bevorzugt zu erweitern.

10.1.2 Fachliche statt technische Struktur#

Die Testsuite wird fachlich und nicht technisch gegliedert. Neue Features werden der fachlich passenden Testgruppe zugeordnet, zum Beispiel boards, relationships, minimap, explorer oder synchronization.

10.1.3 Tests als ausführbare Spezifikation#

E2E-Tests dienen gleichzeitig als Regressionstest, fachliche Dokumentation und ausführbare Spezifikation. Beim Lesen der Tests muss unmittelbar verständlich sein, welche Benutzerfunktion abgesichert wird.

10.1.4 Keine Test-Fragmentierung#

Ein neues Feature darf nicht dazu führen, dass für kleine Erweiterungen neue Testdateien oder neue Obergruppen entstehen. Eine neue Testgruppe ist nur zulässig, wenn ein vollständig neuer fachlicher Themenbereich entsteht und dies vor der Umsetzung dokumentiert wurde.

11. Testdaten#

Testdaten verwenden eindeutige Präfixe.

Beispiel:

PW-Test-

Vor jedem Test:

Nach jedem Test:

Tests dürfen sich gegenseitig nicht beeinflussen.

Cleanup wird auch bei Fehlern versucht.

Datenbankprüfungen und Cleanup dürfen über API oder DB erfolgen, wenn dies die Stabilität erhöht.

Fachliche Funktionalität wird bevorzugt über die UI geprüft.

12. Playwright#

Playwright-Tests werden fachlich dokumentiert.

Hierzu wird test.step() verwendet.

Beispiel:

await test.step("Universum anlegen", async () => {

                });

                await test.step("Bereiche anlegen", async () => {

                });

                await test.step("Systeme anlegen", async () => {

                });

                await test.step("Beziehung erzeugen", async () => {

                });

                await test.step("Cleanup", async () => {

                });

Die Step-Beschreibungen beschreiben die Fachlichkeit.

Nicht die technische Umsetzung.

Playwright-Tests verwenden keine festen Sleeps.

Erlaubt sind:

Nicht erwünscht:

await page.waitForTimeout(1000);

13. Selektoren#

Playwright verwendet bevorzugt eindeutige IDs.

Reihenfolge:

1.

page.locator("#RelationshipsEditorDelete")

2.

ARIA

page.getByRole(...)

3.

Text

Nur wenn keine stabile ID existiert.

XPath soll vermieden werden.

Textselektoren dürfen nicht für fachlich stabile Elemente verwendet werden, wenn eine ID existieren kann.

14. Dokumentation#

Größere Features erhalten:

Öffentliche APIs werden dokumentiert.

Feature Flags, Events, Datenbankmigrationen, I18N-Schlüssel und Revisionslogik werden dokumentiert, sobald sie durch ein Feature betroffen sind.

Dokumentation wird zusammen mit dem Code gepflegt und nicht erst nachträglich erstellt.

15. Codequalität#

Bevorzugt werden:

Code wird regelmäßig refaktoriert.

Refactoring ist Teil der normalen Entwicklung, wenn dadurch bestehende Komplexität reduziert wird.

Nicht erwünscht sind:

16. Review#

Vor Abschluss einer Änderung ist zu prüfen:

16.1 Definition of Done#

Eine Änderung gilt erst dann als fertig, wenn folgende Punkte geprüft wurden:

17. Netzwerksolution-Architekturprinzipien#

Die Netzwerksolution besitzt eine zentrale Architektur. Neue Funktionen erweitern diese Architektur und umgehen sie nicht.

17.1 Single Source of Truth#

Jede fachliche Information besitzt genau eine führende Quelle.

Beispiele:

Mehrfache Datenhaltung ist zu vermeiden.

Falls abgeleitete Daten gespeichert werden, muss klar dokumentiert sein:

17.2 Zentrale UI-Orchestrierung#

Die Steuerung der Benutzeroberfläche erfolgt ausschließlich über den UI-Orchestrator.

Dieser steuert insbesondere:

Komponenten übernehmen diese Aufgaben nicht selbst.

Komponenten dürfen Zustände anzeigen und Benutzeraktionen melden. Die zentrale Entscheidung über Laden, Wechseln und Aktualisieren liegt beim Orchestrator.

17.3 Rendering#

Diagramme werden ausschließlich über den aufgebaut.

Komponenten verändern niemals direkt die Darstellung anderer Komponenten.

Rendering erfolgt ausschließlich über definierte Render-Methoden.

Rendern lädt keine Daten.

Rendern verändert keine fachlichen Daten.

17.4 Komponenten sind unabhängig#

Komponenten kennen keine internen Implementierungen anderer Komponenten.

Kommunikation erfolgt ausschließlich über:

Direkte Zugriffe auf interne Variablen anderer Komponenten sind nicht zulässig.

17.5 Feature-Grenzen#

Ein Feature besitzt genau eine fachliche Verantwortung.

Beispiele:

Boards
                    Darstellung und Navigation

                Relationships
                    Beziehungen

                Explorer
                    Navigation

                Ribbon
                    Werkzeuge

                Sidepanel
                    Eigenschaften

                Universes
                    Verwaltung der Modellräume

Featuregrenzen sollen nicht vermischt werden.

Ein Feature darf andere Features verwenden, aber deren interne Implementierung nicht kennen.

17.6 Wiederverwendung#

Neue Boardtypen verwenden vorhandene Komponenten.

Beispielsweise:

Parallelimplementierungen sind zu vermeiden.

17.7 Wiederverwendbare Standardkomponenten#

Für wiederkehrende UI- und Fachfunktionen werden zentrale Standardkomponenten verwendet.

17.7.1 Rich Text Editor#

Beschreibungstexte, Dokumentationstexte, Hinweise, Kommentare und vergleichbare längere Textfelder verwenden grundsätzlich den zentralen Rich Text Editor.

Es dürfen keine parallelen WYSIWYG-, Markdown-, HTML- oder Texteditor-Komponenten eingeführt werden.

Falls der bestehende Rich Text Editor Anforderungen nicht erfüllt, wird er erweitert.

17.7.2 Einheitliche Eingabeoberflächen#

Fachliche Entitäten dürfen nicht mit eigenen Inline-Formularen, Seitenleistenformularen oder parallelen Detailformularen bearbeitet werden.

Alle Eingaben und Bearbeitungen fachlicher Entitäten erfolgen über den bestehenden Ganzbildschirm-Editor beziehungsweise über eine Erweiterung dieses bestehenden Editor-Musters.

Dies gilt insbesondere für:

Listen, Tabellen und Übersichten dienen ausschließlich der Auswahl, Navigation und kompakten Anzeige.

Sie dürfen keine eigenständige Bearbeitungslogik enthalten.

Zulässig sind dort nur:

Nicht zulässig sind:

Wenn eine Entität bearbeitet werden muss, öffnet die Liste den zentralen Ganzbildschirm-Editor.

Der Ganzbildschirm-Editor verwendet die bestehenden Standardkomponenten:

Neue Eingabekomponenten dürfen nur eingeführt werden, wenn vorher nachgewiesen wurde, dass keine bestehende Komponente geeignet ist. Diese Entscheidung muss im Codepfad dokumentiert werden.

17.7.3 UI-Review vor neuen Formularen#

Vor dem Erstellen eines neuen Formulars muss geprüft und dokumentiert werden:

  1. Welche bestehende Eingabekomponente gibt es bereits?
  2. Warum kann der bestehende Ganzbildschirm-Editor nicht verwendet werden?
  3. Welche bestehende Validierungslogik wird wiederverwendet?
  4. Welche bestehende Speichern-Logik wird wiederverwendet?

Ohne diese Dokumentation darf kein neues Formular erstellt werden.

17.7.4 Abgleichslogik#

Abgleichs-, Vergleichs- und Synchronisationsfunktionen verwenden grundsätzlich die zentrale Abgleichslogik mit der Struktur:

Diese UI und Logik wird für alle vergleichbaren Abgleichsfälle wiederverwendet, z. B.:

Es dürfen keine parallelen Vergleichsoberflächen oder Abgleichslogiken entstehen.

Wenn Wiederverwendung nicht möglich ist, wird vor der Umsetzung begründet, warum eine neue Komponente nötig ist.

17.7 Events#

Events dienen ausschließlich der Kommunikation zwischen unabhängigen Komponenten.

Sie ersetzen keine Programmlogik.

Jedes Event besitzt:

17.8 Laden und Rendern#

Laden und Rendern sind unterschiedliche Vorgänge.

Ablauf:

Daten laden

                ↓

                Modell aktualisieren

                ↓

                Diagramm rendern

Ein Rendern löst niemals automatisch ein erneutes Laden aus.

Reloads erfolgen ausschließlich über den zentralen Orchestrator.

17.9 Fachobjekte#

Alle Fachobjekte verwenden gemeinsame Basiskonzepte.

Neue Objektarten erweitern diese Basiskonzepte.

Speziallösungen sollen vermieden werden.

17.10 Datenmodell#

Die Datenbank bildet ausschließlich das fachliche Modell ab.

Darstellungseigenschaften werden getrennt gespeichert.

Beispiel:

network_objects

                ↓

                network_object_properties

Dieses Prinzip ist bei Erweiterungen beizubehalten.

Datenbanktabellen verwenden sprechende Namen.

Konvention:

network_<fachbegriff_plural>
                network_<fachbegriff>_<detail_plural>

17.11 Backend und Frontend#

Das Frontend kommuniziert ausschließlich über definierte APIs mit dem Backend.

Direkte Datenbankzugriffe aus dem Frontend sind nicht zulässig.

Geschäftslogik gehört grundsätzlich ins Backend oder in klar definierte Fachkomponenten.

APIs verwenden sprechende REST-Endpunkte.

Beispiel:

/api/network/universes
                /api/network/boards
                /api/network/relationships

17.12 Testbarkeit#

Neue Komponenten müssen testbar entwickelt werden.

Dazu gehören insbesondere:

17.13 Erweiterbarkeit#

Vor jeder größeren Änderung ist zu prüfen:

Neue Parallelstrukturen sind zu vermeiden.

17.14 Refactoring#

Bei jeder größeren Änderung ist zu prüfen, ob bestehender Code vereinfacht werden kann.

Technische Schulden sollen reduziert und nicht vergrößert werden.

17.15 Architektur vor Geschwindigkeit#

Eine kurzfristig einfache Lösung darf die langfristige Architektur nicht verschlechtern.

Falls eine gewünschte Änderung gegen diese Richtlinien verstößt, ist dies vor der Umsetzung zu benennen und zu begründen.

Die langfristige Wartbarkeit der Netzwerksolution besitzt Vorrang vor kurzfristigen Implementierungsvorteilen.

17.16 Lesbare Dokumentationsdarstellungen#

Textdarstellungen dienen der Verständlichkeit. Sie dürfen fachliche Aussagen nicht in einer einzigen langen Zeile, in schwer verfolgbaren Pfeilketten oder in überladenen ASCII-Diagrammen verdichten.

Verbindlich gelten folgende Regeln:

Geeignete Darstellungsformen:

Inhalt Bevorzugte Form
einzelne Beziehung kurzer vertikaler Textblock
mehrere Beziehungstypen Tabelle mit Quelle, Relationship, Ziel und Aussage
linearer Ablauf nummerierte Liste oder vertikaler Ablauf
Hierarchie oder Verzeichnis Baumdarstellung
komplexes Netz Tabelle plus erklärender Text; bei Bedarf separates Diagramm

Ungeeignet ist beispielsweise eine Darstellung, die mehrere semantisch unterschiedliche Beziehungen in einer Zeile bündelt.

18. Feature Flags und Feature Modules#

Die Netzwerksolution kann fachliche Funktionen modular aktivieren oder deaktivieren.

Ziel ist, dass einzelne Kunden nur die Funktionen erhalten, die sie tatsächlich benötigen.

Beispiele:

18.1 Feature Flags#

Jedes größere Feature besitzt ein zentrales Feature Flag.

Beispiele:

feature.enterpriseArchitecture
                feature.sparxIntegration
                feature.wordpressSync
                feature.capabilityManagement
                feature.processManagement

Feature Flags werden zentral verwaltet.

Feature-Abfragen dürfen nicht verstreut und uneinheitlich im Code verteilt werden. UI, API und Hintergrundjobs verwenden dieselbe Feature-Registry.

18.2 Feature Registry#

Alle verfügbaren Features werden in einer zentralen Feature Registry beschrieben.

Die Registry enthält mindestens:

18.3 Verhalten bei deaktivierten Features#

Ein deaktiviertes Feature darf nicht sichtbar oder nutzbar sein.

Das betrifft:

Deaktivierte Features dürfen keine Fehler im System verursachen.

APIs deaktivierter Features werden backendseitig abgesichert. Es reicht nicht aus, nur UI-Elemente auszublenden.

18.4 Abhängigkeiten#

Features dürfen Abhängigkeiten besitzen.

Beispiel:

feature.sparxIntegration
                    benötigt feature.enterpriseArchitecture

Wenn ein Basisfeature deaktiviert ist, müssen abhängige Features automatisch deaktiviert oder blockiert werden.

Abhängigkeiten werden nicht im UI-Code hart verdrahtet, sondern über die Feature Registry aufgelöst.

18.5 Tests#

Jedes Feature wird mindestens in zwei Varianten getestet:

E2E-Tests prüfen, dass deaktivierte Features nicht sichtbar und nicht erreichbar sind.

API-Tests prüfen, dass deaktivierte Features nicht unbeabsichtigt über direkte Requests nutzbar sind.

19. Internationalisierung (I18N) und Lokalisierung (L10N)#

Das System kann grundsätzlich alle Sprachen, die von den Kunden benötigt werden, abbilden. Für die Grundausstattung werden Deutsch, Englisch und Ukrainisch vorgegeben.

19.1 Oberflächen#

Die Benutzeroberfläche enthält keine fest codierten Texte.

Alle sichtbaren Texte werden ausschließlich über einen zentralen Übersetzungsdienst geladen.

Dazu gehören insbesondere:

Menüs
                Ribbon
                Explorer
                Dialoge
                Buttons
                Fehlermeldungen
                Tooltips
                Platzhalter
                Kontextmenüs
                Hilfetexte

Neue Komponenten dürfen keine direkt im Code hinterlegten UI-Texte enthalten.

UI-Texte werden über stabile Übersetzungsschlüssel referenziert.

Beispiel:

relationships.editor.title
                relationships.editor.delete
                relationships.editor.direction

19.2 Standardsprache#

Die fachliche Basissprache der Netzwerksolution ist derzeit Deutsch.

Weitere aktiv unterstützte Sprachen sind:

Deutsch
                de

                Englisch
                en

                Ukrainisch
                uk

Die Architektur muss jedoch beliebig viele weitere Sprachen unterstützen.

19.3 Fachdaten#

Nicht nur die Oberfläche ist mehrsprachig.

Auch alle fachlichen Inhalte müssen mehrsprachig verwaltet werden.

Beispiele:

Titel
                Kurzbeschreibung
                Beschreibung
                Dokumentationen
                Kommentare
                Alt-Texte
                Linktitel
                Hinweise
                Glossare
                Markdown
                HTML

Jedes übersetzbare Feld wird im Datenmodell eindeutig als übersetzbar behandelt.

19.4 Zentrale Übersetzung#

Es existiert eine zentrale Übersetzungskomponente.

Diese übernimmt:

automatische Übersetzungen
                Aktualisierung vorhandener Übersetzungen
                Statusverwaltung
                Qualitätskennzeichnung
                spätere Einbindung verschiedener KI-Modelle

Keine Komponente übersetzt Texte selbst.

19.5 Übersetzungsstatus#

Jede Übersetzung besitzt einen Status.

Beispiele:

ORIGINAL
                AUTO_TRANSLATED
                MANUALLY_EDITED
                OUTDATED

Dadurch lässt sich erkennen:

Manuell bearbeitete Übersetzungen werden niemals automatisch überschrieben.

19.6 Änderungsablauf#

Beispiel:

Ein Redakteur bearbeitet die deutsche Beschreibung eines Systems.

Beim Speichern geschieht automatisch:

  1. Original speichern
  2. Hash des Originaltexts bilden
  3. Prüfen, welche Übersetzungen existieren
  4. Für jede Zielsprache prüfen:
existiert keine Übersetzung
                    → automatisch erzeugen

                existiert nur eine automatische Übersetzung
                    → automatisch aktualisieren

                wurde manuell bearbeitet
                    → Status OUTDATED setzen und nicht überschreiben

Dadurch gehen manuelle Übersetzungen niemals verloren.

19.7 Übersetzungsverwaltung#

Es existiert ein eigenständiges Modell für die Übersetzung.

Zum Beispiel:

translation_units

                id
                entity_type
                entity_id
                field_name
                source_language
                target_language
                source_hash
                translation
                status
                translated_at
                translated_by
                reviewed_at
                reviewed_by

Beispiel:

network_object
                42
                description
                de
                en
                7F2A...
                "This system ..."
                AUTO_TRANSLATED

Der source_hash des Originaltexts verhindert unnötige Neuübersetzungen.

Beim Speichern wird geprüft:

Hat sich der Hash geändert?

                Nein
                    → nichts tun

                Ja
                    → Übersetzungsstatus prüfen

Dadurch wird nicht bei jedem Speichern neu übersetzt.

19.8 Vorteile#

Dieses Modell ermöglicht später nahezu ohne Änderungen:

20. Historisierung und Revisionsmanagement#

Die Netzwerksolution verwaltet Unternehmenswissen.

Unternehmenswissen darf niemals unbeabsichtigt verloren gehen.

Daher werden sämtliche fachlichen Änderungen historisiert und nachvollziehbar gespeichert.

20.1 Vollständige Historisierung#

Alle fachlichen Artefakte besitzen eine Versionshistorie.

Hierzu gehören insbesondere:

Physisches Löschen von Nutzdaten erfolgt grundsätzlich nicht.

Stattdessen werden Objekte logisch entfernt oder versioniert.

Harte Löschungen sind nur für technische Bereinigung, Testdaten-Cleanup oder administrative Sonderfälle erlaubt.

20.2 Änderungsprotokoll#

Jede Änderung wird nachvollziehbar protokolliert.

Mindestens gespeichert werden:

Beispiel:

2026-08-14 14:33

                Benutzer:
                Roland

                Objekt:
                System "WordPress"

                Feld:
                Beschreibung

                Alter Wert:
                ...

                Neuer Wert:
                ...

20.3 Undo / Redo#

Alle fachlichen Änderungen müssen rückgängig gemacht werden können.

Das Undo-System arbeitet auf fachlicher Ebene und nicht ausschließlich auf UI-Ebene.

Beispiele:

Jede Änderung besitzt die notwendige Information, um ihren vorherigen Zustand wiederherzustellen.

Redo wird nach Möglichkeit ebenfalls unterstützt.

20.4 Versionierung#

Jede Änderung erzeugt eine neue Revision.

Revisionen sind unveränderlich.

Bereits gespeicherte Revisionen werden niemals überschrieben.

Revisionen beschreiben fachliche Änderungen und sind nicht nur technische Datenbank-Diffs.

20.5 Enterprise Snapshots#

Zusätzlich zu den Einzelrevisionen unterstützt die Netzwerksolution vollständige Enterprise Snapshots.

Ein Enterprise Snapshot beschreibt den Zustand aller relevanten Artefakte zu einem bestimmten Zeitpunkt.

Ein Enterprise Snapshot dient beispielsweise:

20.6 Inhalt eines Enterprise Snapshot#

Ein Enterprise Snapshot umfasst alle fachlich relevanten Informationen.

Beispiele:

Ein Enterprise Snapshot muss vollständig reproduzierbar sein.

20.7 Wiederherstellung#

Aus jedem Enterprise Snapshot kann jederzeit wieder ein Arbeitsstand erzeugt werden.

Dabei werden zwei Verfahren unterstützt:

Enterprise Snapshots dürfen den aktuellen Datenbestand nicht unbeabsichtigt überschreiben.

Die Wiederherstellung erfolgt grundsätzlich als bewusste Benutzeraktion.

20.8 Vergleich#

Beliebige Revisionen oder Enterprise Snapshots können miteinander verglichen werden.

Der Vergleich zeigt mindestens:

Der Benutzer erkennt dadurch nachvollziehbar die Entwicklung des Modells.

20.9 Historie der Übersetzungen#

Übersetzungen besitzen eine eigene Historie.

Es bleibt nachvollziehbar:

20.10 API#

Historisierung ist Bestandteil der Fachlogik.

Das Backend stellt zentrale Funktionen bereit:

Frontend-Komponenten implementieren keine eigene .

20.11 Performance#

Historisierung darf die normale Benutzung nicht beeinträchtigen.

Historien werden effizient gespeichert.

Große Enterprise Snapshots dürfen dedupliziert oder referenziert werden, solange ihre vollständige Wiederherstellung jederzeit gewährleistet bleibt.

20.12 Nachvollziehbarkeit#

Alle fachlichen Änderungen müssen revisionssicher nachvollziehbar bleiben.

Ein Benutzer muss jederzeit beantworten können:

Dieses Prinzip bildet die Grundlage für Auditierbarkeit, Dokumentationspflichten und langfristiges Wissensmanagement innerhalb der Netzwerksolution.

20.13 Baselines#

Neben Enterprise Snapshots unterstützt die Netzwerksolution fachliche Baselines.

Eine Baseline ist ein bewusst freigegebener und benannter Modellstand.

Beispiele:

Baselines sind dauerhaft referenzierbar und werden nicht nachträglich verändert.

21 Lizensierung, Copyright und Nutzung externer Komponenten#

Das Projekt muss jederzeit sicherstellen, dass sämtliche eingesetzten Komponenten, Bibliotheken, Frameworks und sonstigen externen Bestandteile rechtlich zulässig verwendet werden.

Es dürfen keine Lizenzverletzungen oder Copyright-Verstöße entstehen.

21.1 Wiederverwendung vor neuen Abhängigkeiten#

Vor der Einführung einer neuen Library oder eines Frameworks ist grundsätzlich zu prüfen, ob die gewünschte Funktion bereits vorhanden ist.

Dabei gilt folgende Priorität:

  1. Vorhandene Funktionalität der Netzwerksolution wiederverwenden.
  2. Browser- oder Plattformfunktionen verwenden.
  3. Standardbibliotheken der jeweiligen Programmiersprache verwenden.
  4. Bereits vorhandene Projekt-Libraries verwenden.
  5. Erst danach neue externe Libraries evaluieren.

Es dürfen keine Parallelimplementierungen derselben Funktionalität entstehen.

21.2 Verwendung externer Libraries, Frameworks und Dienste#

Externe Komponenten dürfen nur eingesetzt werden, wenn hierfür ein nachvollziehbarer technischer Nutzen besteht.

Dabei gelten folgende Grundsätze:

Vor der Einführung einer neuen Library ist insbesondere zu dokumentieren:

21.3 Lizenzprüfung#

Vor der Verwendung einer externen Komponente ist deren Lizenz zu prüfen.

Dabei ist insbesondere sicherzustellen:

Komponenten mit unklarer oder ungeprüfter Lizenz dürfen nicht verwendet werden.

Alle urheberrechtlich erforderlichen Hinweise sind vollständig einzuhalten.

Insbesondere:

21.5 Sparsamkeit bei externen Abhängigkeiten#

Das Projekt verfolgt das Prinzip der minimalen Abhängigkeiten.

Neue Libraries dürfen nur eingeführt werden, wenn der Nutzen den zusätzlichen Wartungsaufwand rechtfertigt.

Insbesondere gilt:

21.6 Verbot redundanter Libraries#

Für dieselbe Aufgabe darf grundsätzlich nur eine Bibliothek verwendet werden.

Beispiele:

Parallele Implementierungen derselben Funktionalität sind unzulässig.

Bereits vorhandene Komponenten sind konsequent wiederzuverwenden.

21.7 Dokumentation neuer Abhängigkeiten#

Jede neu eingeführte externe Komponente ist im Projekt zu dokumentieren.

Mindestens festzuhalten sind:

Dadurch bleibt die Architektur langfristig nachvollziehbar.

21.8 Änderungen an externem Quellcode#

Direkte Änderungen an eingebundenen Drittbibliotheken sind grundsätzlich zu vermeiden.

Falls eine Anpassung unvermeidbar ist, gelten folgende Regeln:

21.9 Architekturprinzip#

Externe Komponenten dienen ausschließlich der Unterstützung des Projekts.

Die Architektur der Netzwerksolution muss jederzeit unabhängig von einzelnen Libraries bleiben.

Externe Frameworks dürfen die Architektur nicht bestimmen.

Die Geschäftslogik, das Domänenmodell und die Kernarchitektur müssen auch bei einem späteren Austausch einer Library unverändert bestehen bleiben.

22 Serverseitiges Logging und Diagnose#

Das Backend verwendet einen zentralen Logging- und Diagnosemechanismus.

Ein HTTP-500 ohne serverseitigen Logeintrag ist unzulässig.

22.1 Einheitliches Logging#

Alle HTTP-Requests laufen über eine zentrale Middleware.

Einzelne Handler dürfen keine eigene Logging-Architektur aufbauen.

Vor Einführung neuer Logging-Komponenten muss geprüft und dokumentiert werden, ob bestehende Middleware, Response-Komponenten oder Logging-Infrastruktur erweitert werden können.

22.2 Request-ID#

Jeder Request erhält automatisch eine eindeutige Request-ID.

Diese Request-ID erscheint:

Dadurch muss jeder Browserfehler eindeutig dem Serverlog zugeordnet werden können.

22.3 Request-Logging#

Für jeden Request werden mindestens protokolliert:

Query-Parameter mit potentiell sensiblen Inhalten werden nicht ungeprüft geloggt.

22.4 Fehlerlogging#

Jeder HTTP-500 muss serverseitig mit konkretem Fehler protokolliert werden.

Mindestens erforderlich:

Interne technische Details dürfen im Browser nicht offengelegt werden.

Der Browser erhält bei internen Fehlern nur eine neutrale Fehlermeldung und die Request-ID.

22.5 Panic-Recovery#

Das Backend besitzt eine zentrale Panic-Recovery.

Bei einer Panic werden protokolliert:

Der Server muss nach einer Panic weiter erreichbar bleiben.

22.6 Log-Level#

Das Backend unterstützt mindestens folgende Log-Level:

Das aktive Level wird ausschließlich über Konfiguration gesetzt, zum Beispiel:

NS_LOG_LEVEL=INFO
                NS_LOG_LEVEL=TRACE

Eine Änderung des Log-Levels darf keine Codeänderung erfordern.

22.7 TRACE-Modus#

TRACE dient ausschließlich der lokalen Entwicklungsdiagnose.

TRACE darf zusätzliche technische Informationen enthalten, zum Beispiel:

Request-Bodies dürfen nur im TRACE-Modus geloggt werden und müssen vorher auf sensible Daten geprüft werden.

22.8 Datenschutz#

Niemals unmaskiert loggen:

22.9 Activity-Logging#

Fachliches Activity-Logging bleibt vom technischen Serverlogging getrennt.

Technisches Logging ersetzt kein Activity-Logging.

Activity-Logging ersetzt kein technisches Fehlerlogging.

23 Automatisierte serverseitige Tests#

Das Backend besitzt eine zentral ausführbare Go-Testsuite.

Playwright bleibt End-to-End-Test und ersetzt keine serverseitigen Tests.

Serverseitige Tests ersetzen keine End-to-End-Tests.

Beide Testarten ergänzen sich.

23.1 Zentrale Testausführung#

Alle Go-Tests müssen zentral ausführbar sein.

Mindestens unterstützt wird:

go test ./...

Optional können zusätzliche Einstiegspunkte wie Makefile-Ziele oder Skripte bereitgestellt werden.

23.2 Teststruktur#

Tests folgen der bestehenden Architektur.

Beispiele:

internal/components/httpjson/httpjson_test.go
                internal/components/serverdiag/logger_test.go
                internal/features/network/repository_test.go
                internal/features/network/service_test.go
                internal/web/handler_test.go

Es darf keine parallele Testarchitektur entstehen.

23.3 Repository-Tests#

Repositorys werden auf der niedrigstmöglichen Ebene getestet.

Mindestens relevant sind:

23.4 Service-Tests#

Geschäftslogik wird in Service-Tests abgesichert.

Dazu gehören insbesondere:

23.5 Handler-Tests#

REST-Endpunkte erhalten Handler-Tests.

Mindestens geprüft werden:

23.6 Middleware-Tests#

Middleware wird eigenständig getestet.

Mindestens geprüft werden:

23.7 Logging-Tests#

Das technische Logging wird automatisiert geprüft.

Mindestens geprüft werden:

23.8 Migrationstests#

Datenbankmigrationen erhalten Tests.

Geprüft werden:

23.9 Regression#

Jeder reproduzierbare Bug erhält mindestens einen automatisierten Regressionstest.

Ein Bug gilt erst dann als dauerhaft behoben, wenn er auf der niedrigstmöglichen sinnvollen Ebene abgesichert ist.

Richtlinie:

24 Einheitlicher Speicherfluss fachlicher Entitäten#

Fachliche Entitäten verwenden einen einheitlichen Speicherfluss.

Dies gilt insbesondere für:

24.1 Create und Update#

Create und Update sind strikt zu trennen.

Create erzeugt ausschließlich neue Datensätze.

Update aktualisiert ausschließlich bestehende Datensätze.

Die UI entscheidet anhand des Entity-Zustands:

Create darf nicht verwendet werden, wenn eine bestehende Entität mit ID bearbeitet wird.

Update darf nicht ohne ID ausgeführt werden.

Die ID darf beim Öffnen, Bearbeiten, Speichern, Schließen und Reload eines Editors nicht verloren gehen.

24.2 Dublettenprüfung#

Dublettenprüfungen müssen denselben fachlichen Gültigkeitsbereich verwenden wie die Entität selbst.

Beispiele:

Beim Update ist immer zu prüfen:

existiert ein anderer Datensatz mit gleicher fachlicher Identität?

Nicht zulässig ist:

existiert irgendein Datensatz mit gleicher fachlicher Identität?

Der eigene Datensatz muss bei Dublettenprüfungen ausgeschlossen werden.

Unverändertes Speichern eines bestehenden Datensatzes darf keinen Konflikt auslösen.

24.3 Benutzerverwaltete Stammdaten und Migrationen#

Benutzerverwaltete Stammdaten dürfen nach der initialen Migration nicht bei jedem Systemstart oder Repository-Ensure automatisch neu erzeugt werden.

Dies gilt insbesondere für:

Migrationen dürfen bestehende Legacy-Werte in Stammdaten überführen und Referenzen setzen.

Sie dürfen aber gelöschte oder umbenannte Benutzer-Stammdaten nicht selbstheilend wieder anlegen, wenn keine fachliche Referenz mehr existiert.

Default-Seeding ist nur zulässig, wenn es eindeutig als initiale Installationserzeugung abgegrenzt ist und nicht bei jeder späteren Schema-Prüfung erneut wirkt.

24.4 Statuscodes#

Fachliche Save-Fehler verwenden eindeutige HTTP-Statuscodes.

Fachliche Konflikte dürfen nicht als Serverfehler behandelt werden.

Technische Fehler dürfen nicht als fachlicher Konflikt versteckt werden.

24.5 UI-Verhalten#

Die UI muss fachliche Fehler verständlich anzeigen.

Konflikte enthalten eine konkrete Meldung.

Wenn eine Request-ID vorhanden ist, wird sie in der UI angezeigt, damit Browserfehler und Serverlog eindeutig zusammenpassen.

Listen und Übersichten erzeugen keine eigene Speicherlogik.

Speichern erfolgt ausschließlich über den jeweiligen Editor und den zentralen API-Save-Pfad der Entität.

24.5 Tests#

Jede fachliche Entität benötigt Tests für:

Jeder gefundene Save-Flow-Bug wird mindestens auf Handler- oder Repository-Ebene abgesichert.

25. Dokumentationsklassifizierung#

Jedes neue Dokument muss vor dem Erzeugen klassifiziert werden.

Die Klassifizierung ist verbindlich und muss vor der Wahl des Zielpfads erfolgen. Ein Dokument besitzt genau eine primäre Dokumentationsklasse.

Die folgenden Dokumentationsklassen sind für Workspace- und Building-Block-Dokumentation zulässig:

Klasse Zweck Typische Inhalte Zielordner
Architektur Dauerhafte Beschreibung von Struktur, Architekturentscheidungen, Modellen und Abhängigkeiten Workspace-Modell, Runtime-Modell, Build-Modell, Integration, Drift Detection, Entwicklungsprozess, Architekturentscheidungen documents/architecture/
Spezifikation Dauerhafte fachliche oder technische Beschreibung erwarteten Verhaltens Schnittstellenbeschreibungen, Vertragsbeschreibungen, akzeptierte Anforderungen, Daten- oder Verhaltensspezifikationen documents/specification/
Betrieb Dauerhafte Anleitung für Betrieb, Lifecycle, Bedienung und technische Abläufe Betriebsanleitungen, Lifecycle-Werkzeuge, Deployment-Hinweise, Wiederanlauf, manuelle Betriebsabläufe documents/operation/
Validierung Nachweis einer konkreten Prüfung oder Abnahme Feature-Validierungen, Testnachweise, Prüfergebnisse, Abnahmeprotokolle, Konsistenzprüfungen documents/validation/
Reports Zeitbezogene Ergebnis- oder Statusberichte Sprintberichte, Abschlussberichte, Statusberichte, Ergebniszusammenfassungen documents/reports/
Historie Historische, abgelöste oder archivierte Informationen Migrationsnotizen, ersetzte Entscheidungen, archivierte Projektstände, nachvollziehbare Altstände documents/history/

25.1 Pflichtprüfung vor Dokumenterzeugung#

Vor dem Erzeugen eines neuen Dokuments ist verpflichtend zu prüfen, ob bereits eine geeignete Dokumentationsklasse existiert.

Die Prüfung erfolgt vor dem Anlegen der Datei und vor dem Anlegen eines Zielordners. Dabei sind mindestens folgende Fragen zu beantworten:

  1. Welche bestehende Dokumentationsklasse beschreibt den Zweck des Dokuments?
  2. Gibt es bereits ein geeignetes Dokument mit gleicher oder sehr ähnlicher Aufgabe?
  3. Gehört das Dokument in eine dauerhafte Klasse oder ist es ein zeitbezogener Nachweis?
  4. Welcher Zielordner ist durch die gewählte Klasse vorgegeben?
  5. Ist ein neuer Zielordner wirklich erforderlich, oder kann eine bestehende Klasse verwendet werden?

Ein Dokument darf erst erzeugt werden, wenn diese Prüfung abgeschlossen ist.

Wenn eine bestehende Dokumentationsklasse geeignet ist, muss der durch diese Klasse definierte Zielordner verwendet werden.

25.2 Neue Dokumentationsordner nur als Ausnahme#

Neue Dokumentationsordner dürfen nur eingeführt werden, wenn keine bestehende Dokumentationsklasse geeignet ist.

Die Einführung eines neuen Dokumentationsordners ist vor der Umsetzung zu begründen und zu dokumentieren. Die Begründung muss mindestens enthalten:

Ohne diese dokumentierte Begründung darf kein neuer Dokumentationsordner entstehen.

25.3 Keine parallelen Dokumentationsstrukturen#

Für Workspace- und Building-Block-Dokumentation wird ausschließlich die Dokumentationsstruktur aus SolutionArchitecture/20-architecture/concepts/Documentation_Model.md verwendet.

Neue parallele Sammelordner neben dem verbindlichen Dokumentationswurzelordner documents dürfen nicht eingeführt werden, wenn eine bestehende Dokumentationsklasse geeignet ist.

Insbesondere dürfen folgende Ordnernamen nicht als zusätzliche parallele Dokumentationsstruktur eingeführt werden:

documentation
                manual
                notes
                misc
                tmp

Der Name documents ist ausschließlich als verbindlicher Dokumentationswurzelordner des definierten Dokumentationsmodells zulässig.

25.4 Abgrenzung zum globalen Solution-Architecture-Paket#

Das globale Solution-Architecture-Paket verwendet weiterhin seine nummerierte Paketstruktur.

Die hier definierten Klassen steuern die Dokumentation in Workspaces und Building Blocks sowie die fachliche Einordnung neuer Dokumente. Sie ersetzen nicht automatisch die bestehende Struktur des globalen Solution-Architecture-Pakets.

25.5 Keine Dubletten#

Neue Dokumente dürfen bestehende Inhalte nicht duplizieren.

Wenn ein bestehendes Dokument erweitert werden kann, ist Erweiterung der Neuerzeugung vorzuziehen.

Wenn ein Dokument Inhalte mehrerer Klassen enthalten würde, ist die primäre Klasse zu benennen. Eine Aufteilung in mehrere Dokumente darf nur erfolgen, wenn dadurch keine inhaltliche Dublette entsteht.

25.6 Verbindliche Dokumentationsregeln#

Für neue und geänderte Dokumentation gelten zusätzlich verbindlich die folgenden Regeln:

Diese Regeln gelten unabhängig davon, ob ein Dokument manuell, durch ein Werkzeug oder durch KI-Unterstützung erzeugt wird.

25.7 Prüfablauf für neue Dokumentation#

Vor dem Erzeugen eines neuen Dokuments ist der folgende Prüfablauf einzuhalten:

  1. Dokumentationsklasse bestimmen.
  2. Prüfen, ob ein bestehendes Dokument erweitert werden kann.
  3. Prüfen, ob durch das neue Dokument eine Dublette oder parallele Fortschreibung entstehen würde.
  4. Zielordner aus der Dokumentationsklasse ableiten.
  5. Nur wenn keine bestehende Klasse geeignet ist, eine neue Klasse oder ein neuer Zielordner vorschlagen und begründen.
  6. Erst nach dieser Prüfung das Dokument erzeugen.

Das Ergebnis der Prüfung muss im jeweiligen Änderungs- oder Abschlussnachweis nachvollziehbar sein.

25.8 Trennung dauerhafter Dokumentation von Projektartefakten#

Dauerhafte Dokumentation beschreibt stabile Architektur, Spezifikation, Betrieb oder langfristig relevante Historie.

Sprint-, Feature-, Analyse-, Validierungs- und Abschlussartefakte dokumentieren dagegen einen konkreten Arbeitsstand oder Prüfnachweis. Sie dürfen dauerhafte Dokumentation nicht ersetzen und nicht ungeordnet im Hauptverzeichnis eines Workspaces oder Building Blocks abgelegt werden.

Wenn ein Sprint- oder Feature-Ergebnis dauerhaft relevant wird, muss der dauerhafte Inhalt in ein passendes Dokument der Klasse Architektur, Spezifikation, Betrieb oder Historie überführt werden. Der Sprint- oder Feature-Nachweis bleibt ein zeitbezogenes .

99. Environment Neutrality#

Building Blocks und führende Quellartefakte müssen umgebungsneutral bleiben.

Vor Abschluss jeder Änderung ist zu prüfen:

Falls ja, ist die Änderung ein Architekturfehler.

Zulässig sind nur parameterisierte Templates, .env.example-Dateien mit eindeutigem Beispielcharakter oder Werte in der jeweiligen Runtime-Konfiguration.

SQL-Dateien dürfen keine konkreten Datenbanknamen oder Benutzer enthalten. Sie verwenden Platzhalter wie ${DB_NAME}, ${DB_USER} und ${DB_PASSWORD}, die erst während Deployment oder Runtime-Erzeugung aufgelöst werden.

Shell-Skripte müssen die passende Environment- oder Runtime-Konfiguration laden und dürfen Tools wie mariadb, mysql, Webserver oder externe Clients nicht ohne explizite, konfigurierte Parameter aufrufen.

Datenbank-Deployment: Admin- und Anwendungsbenutzer trennen#

Administrative SQL-Operationen (CREATE DATABASE, CREATE USER, GRANT, REVOKE, FLUSH PRIVILEGES) dürfen nicht mit dem Anwendungsbenutzer ausgeführt werden.

Pflichtprüfung:

Ein Verstoß ist ein Architekturfehler.

100. Idempotente Deployments und Migrationen#

Deployment-, SQL- und Migrationsskripte müssen wiederholbar sein.

Vor Abschluss jeder Änderung ist zu prüfen:

Nicht-idempotente Deployment- oder Migrationsschritte sind Architekturfehler und vor Abschluss der Änderung zu korrigieren.

Reviewpunkte für lokale Entwicklungsumgebung#

Änderungen an Workspace-Skripten, lokaler Runtime, systemd-User-Services, Watcher, Import, Export, Tests oder lokaler Datenbankeinrichtung gelten nur als reviewfähig, wenn folgende Punkte geprüft und dokumentiert sind:

Die Prüfung erfolgt gegen workspace/documentation/operation/step-by-step-installation-guide.md und die daraus abgeleiteten Betriebsdokumente.

Reviewpunkte – robuster Build-, Import- und Export-Workflow#

Bei Änderungen am lokalen Entwicklungs-, Import-, Restore-, Export- oder Buildworkflow sind zusätzlich zu prüfen:

26. Zentrale asynchrone Board-Persistenz#

Board-Persistenz ist eine zentrale Infrastrukturverantwortung. UI-Komponenten dürfen Board-Zustände ändern und NSBoards.save(...) aufrufen, implementieren aber keine eigene konkurrierende Persistenzlogik.

Für Board-Saves gilt verbindlich:

Diese Regel verhindert Race Conditions, bei denen ältere HTTP-Antworten neuere UI-Zustände überschreiben.

23. Modularisierungssprints#

Für jeden Modularisierungssprint gelten zusätzlich verbindlich:

70-building-blocks/split-reports/BUILDING_BLOCK_SPLIT_READINESS_CHECK.md
                70-building-blocks/split-reports/BUILDING_BLOCK_SPLIT_REPORT.md

Die Roadmap beschreibt die fachlich gewünschte Reihenfolge der Building Blocks. Sie stellt keine technische dar.

Vor produktiven Codeänderungen muss der Readiness-Check erfolgreich abgeschlossen sein. Nach Abschluss des Sprints ist der Split-Report nach der verbindlichen Vorlage zu erstellen.

ChatGPT Roundtrip dauerhaft: compile-sichere Ownership-Extraktion#

Wenn eine fachliche Ownership eindeutig einem Building Block zugeordnet werden kann, die physische Entfernung aus früherer Monolith aber die Kompilierbarkeit der Runtime brechen würde, ist eine compile-sichere Übergangskopie zulässig. Diese muss in integration-map.json, Split-Report und Lifecycle-Record ausdrücklich dokumentiert werden. Die Übergangskopie darf keine zweite Implementierung sein und muss in einem späteren Server/Core/Persistence-Split aufgelöst werden.

Phase G Final Vacuum Rule#

früherer Monolith ist retired. Neue oder bestehende Arbeitsanweisungen dürfen früherer Monolith nicht mehr als produktiven Runtime-Lieferanten voraussetzen. Platform-Core-Dateien gehören nach BB-001. Fachliche Bestandteile gehören ausschließlich in ihre bestehenden Building Blocks. früherer Monolith darf nur noch als No-op-/Retirement-Nachweis ohne produktive Assembly-Quellen existieren.

Dokumentationsnavigation#

Auto-referenceable Dokumente#

Die folgenden Dokumenttypen gelten als auto-referenceable und müssen entsprechend der Dokumentationsnavigation erreichbar sein:

Verbindliche Regeln#

Praxisgetriebene Architekturentwicklung#

Für Foundation-Dokumente, grundlegende Modelle und wesentliche Architekturentscheidungen gilt ergänzend die führende Schreibcharta der Solution Architecture; sie wird in diesem Repository nicht dupliziert.

Wiederkehrende Praxiserfahrungen werden als Knowledge Stories gesichert, bevor sie abstrahiert werden. Die redaktionelle Überarbeitung verbessert die Lesbarkeit, verändert jedoch keine Fakten. Die KI prüft bei geeigneten Architekturfortschritten aktiv, ob eine passende Geschichte aus der Praxis existiert.

Der verbindliche Knowledge-Engineering-Lebenszyklus und seine Artefaktgrenzen verbleiben in der führenden Solution Architecture. Reports und Publikationen sind Repräsentationen und keine unabhängigen fachlichen Quellen.

↑