MVP-SETUP

MVP-Setup#

Zweck dieses Dokuments#

Dieses Dokument beschreibt die gemeinsame Arbeitsgrundlage für den nächsten grundlegenden Entwicklungsschritt der Netzwerksolution und ihrer Engineering-Umgebung.

Es bündelt die bisher erarbeiteten Erkenntnisse zu

Enterprise Architecture,
dem allgemeinen ,
der konkreten Netzwerksolution,
der Engineering Platform für Continuous Exploration, Continuous Integration und Continuous Deployment,
angeschlossenen Systemen und Connectoren,
Capability-Realisierungen,
Runtimes,
einem ersten datenbankgestützten ,
der Dokumentations- und HTML-Pipeline,
Automatisierung,
Datensicherung,
sowie dem geplanten harten, aber kontrollierten Strukturwechsel.

Das Dokument ist bewusst ausführlich. Es soll in späteren Chats als gemeinsamer Ausgangspunkt dienen, ohne dass der ursprüngliche Gesprächskontext erneut rekonstruiert werden muss.

Es beschreibt eine erste lebende Zielstruktur. Diese Struktur darf in späteren Sprints weiterentwickelt werden. Änderungen erfolgen jedoch nachvollziehbar, schrittweise und auf Basis der hier beschriebenen Verantwortlichkeiten.

Status und Einordnung#

Das MVP-Setup ist eine verbindliche Arbeitsgrundlage für

die Reparatur des aktuell benötigten Roundtrips,
die Vorbereitung des harten Strukturschnitts,
den parallelen Aufbau neuer Root-Verzeichnisse und Git-Repositories,
die kontrollierte Übernahme bestehender Inhalte,
und die zeitnahe Implementierung eines ersten UI-gesteuerten Systems.

Es ist noch keine vollständig promovierte Endarchitektur. Insbesondere die endgültigen Repository-Namen, Remote-Namen und einzelne technische Details werden vor dem harten Schnitt noch einmal gemeinsam bestätigt.

Ausgangssituation#

Die bestehende Netzwerksolution enthält heute gleichzeitig

allgemeine Architekturgrundlagen,
die konkrete Architektur der Netzwerksolution,
Engineering- und Roundtrip-Komponenten,
Deployment-Strukturen,
generierte Reports,
Runtime-Verzeichnisse,
Building Blocks,
sowie verschiedene Integrations- und Automatisierungsmechanismen.

Diese Struktur war für die bisherige Entwicklung wertvoll. Sie hat die gemeinsame Architekturarbeit, Building-Block-Analysen, Dokumentationssprints und den Roundtrip ermöglicht.

Mit zunehmender Reife führt die gleichzeitige Verantwortung für Architektur, Implementierung, Engineering und Runtime jedoch zu Problemen:

Repository- und Git-Grenzen sind nicht eindeutig.
Laufzeitdaten und dauerhafte Dokumentation beeinflussen sich gegenseitig.
Importer und Publisher müssen zu viele Sonderfälle kennen.
Allgemeine Modelle liegen teilweise in solution- oder engineering-spezifischen Bereichen.
Building Blocks sind als kleine Diskussions- und Entwicklungseinheiten wertvoll, führen als jeweils eigenständige Git-Grenze jedoch zu hohem Verwaltungsaufwand.
ZIP-Austauschpakete werden unnötig groß oder zu zahlreich.
Der aktuelle Roundtrip ist eng an die bestehende Verzeichnisstruktur gekoppelt.

Der nächste Entwicklungsschritt soll diese Probleme nicht durch weitere Sonderregeln kompensieren. Stattdessen wird parallel zum bestehenden System eine neue, klar getrennte Struktur aufgebaut.

Grundsatz des harten Schnitts#

Die bestehende Netzwerksolution wird nicht im laufenden Betrieb vollständig umgebaut.

Sie bleibt zunächst als eingefrorenes Basissystem erhalten. Aus ihr werden benötigte Artefakte, Dokumente, Skripte, Konzepte und Implementierungen kontrolliert kopiert, fachlich neu eingeordnet, angepasst und in der neuen Struktur validiert.

Der eingefrorene Ausgangsstand bleibt als Referenz verfügbar. Er wird nicht rückwirkend bereinigt und nicht schrittweise so verändert, dass sein bisheriges Zusammenspiel unverständlich wird.

Der neue Aufbau erfolgt parallel in neuen Root-Verzeichnissen.

Der zentrale Migrationsgrundsatz lautet:

Bestehende Artefakte werden kopiert, fachlich neu eingeordnet, angepasst und validiert. Der eingefrorene Ausgangsstand bleibt unverändert als Referenz und Quelle erhalten.

Damit wird ein Big-Bang-Umbau vermieden. Gleichzeitig entsteht keine dauerhafte Doppelpflege, weil jedes migrierte in der neuen Struktur eine eindeutig führende Quelle erhält.

1. Architektur- und Produktlandschaft#

1.1 Enterprise Architecture und allgemeines Metamodell#

Die übergeordnete Architektur beschreibt allgemeine Grundlagen, die nicht ausschließlich für eine einzelne Solution oder für die Engineering Platform gelten.

Dazu gehören insbesondere:

Vision und langfristiges ,
allgemeine Theorien,
das Metamodell für Artefakte, Beziehungen, Capabilities und weitere Dimensionen,
allgemeine Architekturprinzipien,
Knowledge- und Dokumentationsmodelle,
allgemeine Terminologie,
allgemeine UI- und Interaktionsprinzipien,
solutionübergreifende Governance,
sowie gemeinsame Fähigkeiten, die nicht mehrfach implementiert oder fachlich neu definiert werden sollen.

Ein Beispiel ist der Rich Text Editor.

Das Architecture Universe soll nicht für jede Solution oder Plattform einen eigenen Rich Text Editor mit eigenem Inhaltsmodell, eigenen Formatierungsregeln und eigener Speicherung entwickeln. Stattdessen wird ein gemeinsames Rich-Text-Konzept definiert, das von den verschiedenen Solutions und Plattformen verwendet werden kann.

Die allgemeine Architektur beschreibt dabei

das Rich-Text-Artefaktmodell,
erlaubte Strukturen,
Beziehungen zu anderen Artefakten,
Sicherheits- und Validierungsregeln,
Austausch- und Exportformate,
sowie die allgemeine .

Die konkrete Implementierung kann von einer Plattform oder Solution bereitgestellt werden. Das fachliche Modell und die allgemeine Capability werden jedoch nur einmal definiert.

1.2 Konkrete Netzwerksolution Architecture#

Die konkrete Dokumentation der Netzwerksolution beschreibt, was umgesetzt werden muss, damit die Netzwerksolution sinnvoll betrieben und verwendet werden kann.

Sie beschreibt unter anderem

den fachlichen Zweck der Netzwerksolution,
die konkreten Nutzer- und Betriebsszenarien,
die von der Netzwerksolution benötigten Capabilities,
deren Zuordnung zu logischen Komponenten,
die Anforderungen an Benutzer, Rollen und Berechtigungen,
die Nutzung des Universums,
Artefakte und Beziehungen innerhalb der Netzwerksolution,
die notwendigen Connectoren,
die Qualitäts-, Sicherheits- und Datenschutzanforderungen,
sowie die konkrete Realisierung und den Betrieb der Netzwerksolution.

Allgemeine Modelle werden in der Netzwerksolution nicht erneut definiert. Die Netzwerksolution referenziert die übergeordneten Enterprise-Modelle und konkretisiert ausschließlich die für diese Reference Solution notwendigen Anforderungen und Ausprägungen.

1.3 Engineering Platform#

Die Engineering Platform ist das System, das Continuous Exploration, Continuous Integration und Continuous Deployment unterstützt.

Continuous Exploration umfasst insbesondere

die Analyse neuer Anforderungen und Ideen,
Architektur- und Capability-Entwicklung,
Findings und Decision Candidates,
Roadmaps,
Experimente,
sowie die kontrollierte Übernahme validierter Erkenntnisse.

Continuous Integration umfasst insbesondere

die Integration geänderter Artefakte,
Import und Export,
Validierung,
Build,
Tests,
Konsistenzprüfung,
Materialisierung,
und die Erzeugung nachvollziehbarer Engineering-Nachweise.

Continuous Deployment beziehungsweise Delivery umfasst insbesondere

Packaging,
,
Bereitstellung,
Runtime-Konfiguration,
Release- und Baseline-Verwaltung,
sowie die kontrollierte Auslieferung in Test- und Produktivumgebungen.

Der aktuelle Roundtrip ist eine frühe, spezialisierte Implementierung dieser Aufgaben. Er ist nicht mit der langfristigen Engineering Platform gleichzusetzen.

Die Engineering Platform soll künftig selbst vollständig dieselben Artefakt-, Beziehungs-, Capability-, Benutzer- und Governance-Modelle verwenden wie andere Solutions.

Sie darf keine parallele Spezialwelt mit eigenen, nur im Roundtrip bekannten Konzepten bleiben.

1.4 Angeschlossene Systeme und Integrationsarchitektur#

Lokale KI, Container, Translation Services, WordPress, Sparx Enterprise Architect, Datenbanken, APIs, Dateisysteme und weitere externe Systeme werden grundsätzlich als angeschlossene Systeme beziehungsweise Capability Provider betrachtet.

Die Anbindung erfolgt über ein gemeinsames Connector-Management.

Der fachliche Grundsatz lautet:

Externe Systeme und Services werden über Connectoren, deren Capabilities, Operationen, Artefakte und Beziehungen integriert. Sie werden nicht als jeweils eigenständige Integrationssonderfälle implementiert.

Die bereits für WordPress und Sparx vorgesehene Rolle von BB-014 – Connector Management wird daher verallgemeinert.

Connector Management soll künftig mindestens folgende Arten von Capability Providern integrieren können:

Content- und Publikationssysteme wie WordPress,
Architektur-Repositories wie Sparx Enterprise Architect,
Translation Services wie LibreTranslate,
lokale und entfernte KI-Runtimes,
Container und Containerplattformen,
Datenbanken,
Build- und Testwerkzeuge,
Dateisysteme,
externe APIs,
sowie zukünftige interne oder externe Services.

Ein Connector beschreibt mindestens

den angebundenen Provider,
den Connector-Typ,
die angebotenen Capabilities,
die verfügbaren Operationen,
Authentifizierungs- und Sicherheitsanforderungen,
unterstützte Artefakttypen,
Eingaben und Ausgaben,
Fehler- und Retry-Verhalten,
Runtime-Anforderungen,
sowie Beziehungen zu anderen Artefakten und Komponenten.

Beispiel Translation :

Connector
                  Typ: Translation Service
                  Provider: LibreTranslate
                  Capabilities:
                    - Machine Translation
                    - Language Detection
                  Operationen:
                    - translate
                    - detect-language

Beispiel lokale KI:

Connector
                  Typ: AI Runtime
                  Provider: lokale AI Runtime
                  Capabilities:
                    - Text Generation
                    - Summarization
                    - Embeddings
                    - Classification
                  Operationen:
                    - generate
                    - summarize
                    - embed
                    - classify

Beispiel Sparx:

Connector
                  Typ: Architecture Repository
                  Provider: Sparx Enterprise Architect
                  Capabilities:
                    - Model Read
                    - Model Write
                    - Artifact Import
                    - Relationship Synchronization

Translation Services und lokale AI werden damit aus Sicht der Architektur genauso behandelt wie WordPress und Sparx: als externe Systeme mit definierten Connectoren, Capabilities, Operationen, Artefakten und Beziehungen.

2. Repository- und Git-Zielbild#

2.1 Grundsatz#

Git-Grenzen werden nicht aus der Dokumentenstruktur oder aus der Anzahl logischer Komponenten abgeleitet.

Ein eigenes Git-Repository ist nur dann gerechtfertigt, wenn ein tatsächlich unabhängiger Lebenszyklus vorliegt, beispielsweise durch

einen eigenen Release-Zyklus,
eine eigene Verantwortungs- oder Berechtigungsgrenze,
unabhängige Wiederverwendung,
getrennte technische Auslieferung,
oder eine deutlich eigenständige Entwicklung.

Ein gemeinsames Git-Repository erzeugt keinen Monolithen. Ein Monolith entsteht durch unklare Abhängigkeiten, fehlende Schnittstellen und nicht durch die bloße gemeinsame .

2.2 Arbeitsnamen der neuen Root-Repositories#

Als Arbeitsgrundlage werden folgende getrennte Roots verwendet:

enterprise-architecture/
                engineering-platform/
                netzwerksolution-architecture/
                netzwerksolution/
                runtime/

Die endgültigen Namen werden vor dem harten Schnitt bestätigt.

enterprise-architecture#

Dieses Repository enthält die allgemeine Enterprise Architecture und das solutionübergreifende Metamodell.

engineering-platform#

Dieses Repository enthält die logische Engineering Platform, ihre Dokumentation und ihre Implementierungsquellen.

netzwerksolution-architecture#

Dieses Repository enthält ausschließlich die konkrete Architektur der Reference Solution Netzwerksolution.

netzwerksolution#

Dieses Repository enthält die konkrete Implementierung der Netzwerksolution und deren Capability-Realisierungen.

runtime#

Dieser Root enthält konkrete Installationen, Laufzeitumgebungen, Inboxen, Outboxen, Reports, Packages, Logs und Zustände.

2.3 Bestehendes System#

Das bestehende System bleibt zunächst an seinem heutigen Ort erhalten.

Es wird nicht sofort in einen legacy-Ordner verschoben und nicht technisch umbenannt, solange dies den aktuellen Roundtrip oder den laufenden Betrieb gefährden könnte.

Es dient als

eingefrorene Baseline,
funktionierende Referenz,
Quelle für kontrollierte Kopien,
und Vergleichssystem für die neue Implementierung.

Nach erfolgreicher Ablösung kann es später eindeutig als Legacy-System archiviert werden.

3. Building Blocks und Capability-Realisierung#

3.1 Ursprünglicher Zweck der Building Blocks#

Die Building Blocks wurden eingeführt, damit kleine, abgegrenzte Komponenten

entwickelt,
analysiert,
mit einer KI diskutiert,
dokumentiert,
getestet,
und einzeln ausgetauscht werden können.

Dieser Zweck bleibt wichtig.

Die heutige technische Konsequenz, für jeden ein eigenständiges Git-Repository zu führen, ist jedoch zunehmend hinderlich.

Sie erzeugt

viele Repository-Grenzen,
hohen Packaging- und Importaufwand,
schwierige gemeinsame Änderungen,
uneindeutige Abhängigkeiten,
und unnötig viele ZIP-Pakete.

3.2 Neue Rolle der Building Blocks#

Die architektonische Verantwortung der Building Blocks bleibt erhalten.

Für die konkrete Implementierung werden daraus Capability Realization Modules beziehungsweise klar abgegrenzte Capability-Realisierungen.

Die Traceability lautet künftig:

Capability
                  ↓
                Building Block oder logische Komponente
                  ↓
                Capability Realization Module
                  ↓
                Runtime Deployment

Ein Building Block beschreibt die logische Architekturverantwortung.

Ein Capability Realization Module enthält die konkrete Implementierung einer oder mehrerer eindeutig benannter Capabilities beziehungsweise Teilfähigkeiten.

3.3 Gemeinsames Git, getrennte ZIPs#

Die Capability Realization Modules einer Solution können in einem gemeinsamen Git-Repository liegen.

Sie bleiben dennoch einzeln exportierbar und bearbeitbar.

Beispiel:

netzwerksolution/
                  capabilities/
                    terminology/
                      module.yaml
                      documentation/
                      src/
                      tests/
                      packaging/
                    user-management/
                    semantic-resolution/
                    universe-registry/

Ein Modul-ZIP enthält nur das betreffende Modul und ein Manifest.

Beispiele:

terminology.capability.zip
                user-management.capability.zip
                semantic-resolution.capability.zip

Damit können kleine Einheiten mit einer KI ausgetauscht und bearbeitet werden, ohne für jedes Modul ein eigenes Git-Repository zu erzwingen und ohne das gesamte Produktrepository mit Tausenden Dateien übertragen zu müssen.

3.4 Regeln gegen einen unkontrollierten Monolithen#

Jedes Capability Realization Module besitzt ein verbindliches Manifest.

Dieses beschreibt mindestens

ID und Name,
realisierte Capabilities,
öffentliche Schnittstellen,
erlaubte Abhängigkeiten,
benötigte Connectoren,
Runtime-Anforderungen,
Test- und Packaging-Einstiege,
sowie Ownership.

Module dürfen nicht direkt auf interne Implementierungsdetails anderer Module zugreifen.

Kommunikation erfolgt über

definierte Interfaces,
Events,
Verträge,
Connectoren,
oder explizite Shared Contracts.

Zyklische Abhängigkeiten sind nicht zulässig, sofern sie nicht ausdrücklich analysiert und entschieden wurden.

Ein Modul muss separat testbar und separat paketierbar bleiben.

Gemeinsame Funktionen werden erst dann in gemeinsame Module verschoben, wenn eine tatsächliche, mehrfach belegte Wiederverwendung vorliegt.

4. Trennung von logischer Plattform und Runtime#

4.1 Engineering Platform als logisches System#

Die Engineering Platform enthält

logische Komponenten,
Engineering Services,
Capabilities,
Prozesse,
Governance,
Daten- und Informationsmodelle,
Connector-Verträge,
,
Tests,
Referenzkonfigurationen,
sowie die dauerhafte Dokumentation.

Sie enthält keine konkreten produktiven Laufzeitstände.

4.2 Runtime als eigener Bereich#

Die Runtime enthält alle konkreten Instanzen und Ausführungszustände.

Dazu gehören

Inbox,
Outbox,
installierte Repository-Kopien,
Testplattformen,
Acceptance-Plattformen,
Produktionsplattformen,
lokale Container,
generierte HTML-Seiten,
Reports,
Packages,
Run-History,
Logs,
,
temporäre Working Areas,
und konkrete Capability Snapshots.

Als bevorzugte Grundstruktur wird eine umgebungsorientierte Sicht geprüft:

runtime/
                  test-platform/
                    netzwerksolution/
                    engineering-platform/
                    connectors/
                  prod-platform/
                    netzwerksolution/
                    engineering-platform/
                    connectors/
                  local-services/
                    local-ai/
                    translation/
                    databases/

Diese Sicht hat den Vorteil, dass Test und Produktion jeweils als vollständige Plattforminstanz nachvollziehbar sind.

Die endgültige Runtime-Struktur wird vor der Implementierung bestätigt.

4.3 Git-Regeln#

Architektur- und Plattform-Repositories enthalten ausschließlich dauerhafte Quellen und Dokumentation.

Generierte Laufzeitartefakte werden dort nicht versioniert.

Der Runtime-Bereich erhält eigene Git- und Ignore-Regeln.

Konfigurationen, Layouts und reproduzierbare Deployment-Definitionen können versioniert werden.

Nicht versioniert werden insbesondere

Secrets,
produktive Daten,
Logs,
Cache,
temporäre Arbeitsstände,
und sensible Dumps.

5. Engineering Platform als Anwendung des eigenen Metamodells#

5.1 Problem der heutigen Speziallösung#

Der aktuelle Roundtrip orientiert sich teilweise am Metamodell, besitzt daneben jedoch zahlreiche spezialisierte Dateien, Skripte, Verzeichnisregeln und technische Sonderfälle.

Dadurch besteht die Gefahr, dass die Engineering Platform langfristig eine zweite, parallele Modellwelt entwickelt.

5.2 Ziel#

Die Engineering Platform wird selbst zu einer konkreten Anwendung des gemeinsamen Metamodells.

Sie verwaltet ihre eigenen

Artefakte,
Beziehungen,
Capabilities,
Benutzer,
Rollen,
Prozesse,
Automatisierungen,
Reports,
Dokumentationen,
Connectoren,
Deployments,
Baselines,
und Runtime-Zuordnungen

mit denselben Modellen und Mechanismen, die später anderen Solutions zur Verfügung stehen.

Die Engineering Platform wird damit nicht nur ein Werkzeug zur Entwicklung der Netzwerksolution. Sie wird zugleich ein früher praktischer Anwendungsfall und eine Validierung des gemeinsamen Metamodells.

6. MVP des neuen UI-gesteuerten Systems#

6.1 Ziel des MVP#

Sehr zeitnah soll ein erstes UI-gesteuertes System entstehen, das die vorhandene Dokumentation und die Roundtrip-Themen verwaltet.

Das MVP soll keine vollständige Netzwerksolution und keine vollständige Engineering Platform implementieren.

Es soll einen kleinen, betriebsfähigen Kern bereitstellen, der

Artefakte und Beziehungen persistent verwaltet,
Benutzer und Rollen berücksichtigt,
vorhandene Markdown- und HTML-Informationen abbilden kann,
die Dokumentationspipeline aus verwalteten Artefakten betreibt,
Automatisierungen als Artefakte und Beziehungen beschreibt,
und eine belastbare Sicherung und Rekonstruktion ermöglicht.

6.2 Technologie#

Serverseitig wird Golang verwendet.

Browserseitig wird JavaScript verwendet.

Für die erste Persistenz wird MariaDB verwendet.

Diese Entscheidungen beruhen auf vorhandener Infrastruktur und vorhandenem Wissen. Für den ersten MVP ist keine erneute Technologieanalyse erforderlich.

Die Implementierung bleibt dennoch so geschnitten, dass Datenbank, Browser- und Connector-Grenzen ausdrücklich modelliert sind.

6.3 Erste Benutzer und Rollen#

Das MVP wird für wenige Benutzer in Betrieb genommen.

Mindestens drei Referenzbenutzer beziehungsweise Rollen werden vorgesehen.

User 1 – automatischer CE/CI/CD-Benutzer#

Dieser Benutzer führt automatisierte Engineering-Operationen aus.

Er darf

Artefakte und Beziehungen lesen,
freigegebene Automatisierungen ausführen,
neue Versionen erzeugen,
Reports und Packages erstellen,
Validierungen ausführen,
und ausschließlich explizit freigegebene Artefakte verändern.

User 2 – Administrator#

Der Administrator darf

Benutzer und Rollen verwalten,
Artefakttypen und Beziehungstypen konfigurieren,
Connectoren und Runtimes konfigurieren,
Promotions und Baselines genehmigen,
sowie administrative und diagnostische Funktionen ausführen.

User 3 – Editor#

Der Editor darf

Dokumentationsartefakte erstellen und bearbeiten,
Beziehungen pflegen,
den gemeinsamen Rich Text Editor verwenden,
vorhandene Inhalte strukturieren,
und definierte Publikations- oder Review-Prozesse anstoßen.

Er darf keine grundlegende Plattform- oder Runtime-Konfiguration verändern.

Die Benutzer werden nicht dauerhaft hart codiert. Sie dienen als MVP-Referenzfälle für das Rollen- und Berechtigungsmodell.

7. Datenmodell des MVP#

7.1 Ziel#

Das Datenmodell muss Artefakte und Beziehungen mit vielen Dimensionen abbilden können.

Es soll ausreichend stabil sein, um Dokumentation, Engineering-Prozesse, Benutzer, Automatisierungen und Connectoren zu verwalten, ohne für jede neue eine neue Spezialtabelle oder Spalte erzwingen zu müssen.

7.2 Relationaler Kern#

Der MVP erhält einen stabilen relationalen Kern.

Mindestens vorgesehen sind:

Artifact
                ArtifactType
                Relationship
                RelationshipType
                Capability
                User
                Role
                Permission
                Version
                Status
                PropertyDefinition
                PropertyValue
                Connector
                ConnectorOperation
                Runtime
                Automation

Der relationale Kern stellt sicher, dass zentrale Identitäten, Beziehungen, Rechte und Lebenszyklen konsistent und auswertbar bleiben.

7.3 Erweiterbare Eigenschaften#

Zusätzliche Dimensionen werden über kontrollierte Property Definitions und Property Values ergänzt.

Dadurch können Artefakte unterschiedliche, typisierte Eigenschaften besitzen, ohne dass der Kern für jeden neuen Anwendungsfall strukturell erweitert werden muss.

Die erweiterbaren Eigenschaften ersetzen nicht die zentralen relationalen Beziehungen.

Identität, Ownership, Version, Status, Artefakttyp, Beziehungstyp und sicherheitsrelevante Informationen bleiben ausdrücklich modelliert.

7.4 Identität und Versionierung#

Artefakte erhalten stabile IDs.

Versionen werden nicht ausschließlich aus Dateipfaden oder Dateinamen abgeleitet.

Ein Artefakt kann unterschiedliche Materialisierungen besitzen, beispielsweise

Datenbankdarstellung,
Markdown-Darstellung,
HTML-Darstellung,
JSON- oder API-Darstellung,
Package-Darstellung.

Diese Materialisierungen gehören zu derselben Artefaktidentität und werden über Beziehungen und Versionierungsinformationen nachvollziehbar gehalten.

8. Dokumentation, Markdown und HTML#

8.1 Zielbild#

Die heute vorhandenen Markdown- und HTML-Seiten werden schrittweise zu Sichten auf verwaltete Artefakte.

Der geplante Fluss lautet:

verwaltete Artefakte und Beziehungen
                  ↓
                Publisher
                  ↓
                Markdown
                  ↓
                HTML

Ein kontrollierter Rückweg bleibt möglich:

Markdown
                  ↓
                Extractor oder Importer
                  ↓
                verwaltete Artefakte und Beziehungen

8.2 Quellenmodell#

Für den MVP gilt als Ziel:

Die Datenbank ist die operative Quelle des laufenden Systems.
Markdown ist das menschenlesbare, portable, diffbare und rekonstruierbare Austausch- und Sicherungsformat.
HTML ist die veröffentlichte Präsentationssicht.

Kurz:

DB = operative Quelle
                Markdown = portable und rekonstruierbare Materialisierung
                HTML = veröffentlichte Sicht

Eine direkte Änderung an Markdown darf nicht unkontrolliert konkurrierend zur Datenbank wirken.

Änderungen werden über einen definierten Import- oder Synchronisationsprozess übernommen.

Während der Übergangsphase kann der bestehende Markdown-basierte Roundtrip weiterhin führend sein. Der Wechsel der operativen Quelle erfolgt erst nach einem ausdrücklich validierten Migrationsschritt.

8.3 Rich Text Editor#

Das UI verwendet einen gemeinsamen Rich Text Editor auf Basis des übergeordneten Rich-Text-Modells.

Der Editor erzeugt keine proprietäre, nicht rekonstruierbare Inhaltswelt.

Inhalte müssen

strukturiert,
validierbar,
versionierbar,
exportierbar,
und in Markdown beziehungsweise ein langfristig tragfähiges Austauschformat materialisierbar sein.

9. Automatisierung als Artefakte und Beziehungen#

9.1 Grundsatz#

Automatisierungsskripte werden nicht nur als lose Dateien betrachtet.

Jede Automatisierung wird als Artefakt mit Beziehungen beschrieben.

Ein Automation Artifact enthält mindestens

Zweck,
Eingabeartefakte,
Ausgabeartefakte,
benötigte Capabilities,
Connector-Abhängigkeiten,
Runtime-Anforderungen,
Ausführungsoperation,
Validierung,
Fehlerverhalten,
Version,
und Ownership.

Beziehungen beschreiben beispielsweise:

Automation
                  consumes Artifact Type
                  produces Report
                  requires Connector
                  runs in Runtime
                  validates Capability Realization

Der konkrete Go-, Shell- oder JavaScript-Code ist eine Realisierung des Automation Artifact.

9.2 Installierbarkeit#

Die neue Lösung soll ohne umfangreiche manuelle Konfiguration installierbar sein.

Dafür werden notwendige Installations- und Anpassungsschritte ebenfalls als Artefakte und Beziehungen beschrieben.

Aus diesen Informationen können Automatisierungsskripte erzeugt, parametrisiert oder angepasst werden.

Umgebungsabhängige Werte werden nicht hart codiert.

Dazu gehören insbesondere

Datenbanknamen,
Benutzer,
Passwörter,
Hosts,
Ports,
URLs,
Dateisystempfade,
Runtime-Namen,
Secrets,
Zertifikate,
API-Keys,
und externe Endpunkte.

10. Datensicherheit und Rekonstruktion#

10.1 Markdown-Extraktion#

Alle relevanten verwalteten Inhalte werden regelmäßig automatisiert als Markdown beziehungsweise als definierte portable Artefaktformate extrahiert.

Diese Extraktion ist

menschenlesbar,
diffbar,
unabhängig von MariaDB nutzbar,
und zur Rekonstruktion geeignet.

10.2 Datenbank-Dump#

Zusätzlich wird MariaDB automatisiert gesichert.

Der Datenbank-Dump erhält

Prüfsummen,
Zeit- und Baseline-Bezug,
Schema- und Migrationsstand,
sowie eine eindeutige Zuordnung zur Runtime.

10.3 Weitere Sicherungsbestandteile#

Zusätzlich werden vorgesehen:

versionierte Datenbankschemas,
idempotente Migrationen,
Sicherung von Attachments und Binärartefakten,
automatisierte Restore-Tests,
Prüfsummen,
und regelmäßige Testwiederherstellungen.

Eine Sicherung gilt erst dann als belastbar, wenn eine Wiederherstellung praktisch getestet wurde.

11. Reparatur des aktuellen Roundtrips#

11.1 Zweck der Reparatur#

Der aktuell defekte Roundtrip muss repariert werden, weil er für die kontrollierte Realisierung der neuen Struktur weiterhin benötigt wird.

Die Reparatur dient nicht dazu, die bestehende Struktur langfristig weiter auszubauen.

Sie stellt einen stabilen Übergangsprozess bereit, mit dem

aktuelle Repositorys gelesen,
changed-only Overlays importiert,
Reports erzeugt,
ZIPs geprüft,
und die neuen Strukturen schrittweise materialisiert werden können.

11.2 Reparaturgrundsatz#

Die Reparatur erfolgt minimal und nachvollziehbar.

Neue Zukunftsstrukturen werden nicht durch immer weitere Sonderfälle in den alten Roundtrip eingebaut.

Der bestehende Roundtrip wird so weit stabilisiert, dass er

die bestehenden Repositorys zuverlässig verarbeitet,
Fehlerreports erzeugt,
Git- und Snapshot-Verträge korrekt einhält,
leere oder noch nicht vollständig angelegte Roots toleriert,
und kleine, kontrollierte Migrationspakete einspielen kann.

Die neue Runtime- und Repository-Struktur wird anschließend parallel aufgebaut.

11.3 Abnahmekriterien für die Reparatur#

Der reparierte Roundtrip muss mindestens nachweisen:

Ein Workspace changed-only Overlay kann fehlerfrei installiert werden.
Ein Solution-Architecture changed-only Overlay kann fehlerfrei installiert werden.
Nicht vorhandene neue Roots führen nicht zu einem fehlerhaften Pflichtlauf.
Git-Snapshots werden nur dort erzwungen, wo tatsächlich ein Git-Repository vorhanden ist.
Erstinstallationen und spätere Overlay-Updates sind getrennt behandelt.
Fehlende Dateien in ZIPs werden niemals als implizite Löschung interpretiert.
Verbotene Löschungen werden vor der Materialisierung abgewiesen.
Reports und HTML-Ausgaben werden nur für vollständig erkennbare Artefaktquellen erzeugt.
Alle Pflichtprüfungen liefern nachvollziehbare Fehlerreports.
Der Roundtrip kann kleine Migrationspakete für den parallelen Neuaufbau verarbeiten.

11.4 Übergangsstatus#

Der reparierte Roundtrip bleibt eine Übergangslösung.

Seine Funktionen werden schrittweise in die neue, UI-gesteuerte Engineering Platform überführt.

Bis zu dieser Übernahme bleibt er für Migration, Validierung und Packaging verfügbar.

12. Geplante Umsetzung in weiteren Chats#

12.1 Grundstruktur anlegen#

In einem folgenden Chat werden die neuen Root-Verzeichnisse und Git-Grenzen finalisiert und angelegt.

Dabei werden zunächst nur

Repository-Roots,
Manifeste,
Einstiegspunkte,
minimale README-Dateien,
Git-Grundlagen,
und gemeinsame Konfigurationsverträge

angelegt.

Es erfolgt noch keine unkontrollierte Inhaltsmigration.

12.2 Dokumentation schrittweise übernehmen#

Für jeden weiteren Schritt wird nur die Dokumentation übernommen, die für diesen Schritt notwendig ist.

Jedes Artefakt wird dabei geprüft:

Gehört es zur Enterprise Architecture?
Gehört es zur Engineering Platform?
Gehört es zur Netzwerksolution Architecture?
Gehört es zur Implementierung der Netzwerksolution?
Gehört es ausschließlich in die Runtime?

Die Übernahme erfolgt durch Kopie, fachliche Anpassung und Validierung.

12.3 Erstes UI-gesteuertes System implementieren#

Sehr zeitnah wird das erste UI-gesteuerte MVP implementiert.

Der erste sinnvolle Umfang umfasst

Anmeldung und die drei Referenzrollen,
Artefaktübersicht,
Anzeige und Bearbeitung ausgewählter Dokumentationsartefakte,
Beziehungen zwischen Artefakten,
gemeinsamer Rich Text Editor,
Speicherung in MariaDB,
Markdown-Extraktion,
HTML-Publikation,
erste Automatisierungsartefakte,
sowie eine minimale administrative Oberfläche.

Die vorhandene HTML-Pipeline wird schrittweise so umgestellt, dass sie aus den verwalteten Artefakten betrieben wird.

13. Migrationsreihenfolge#

Die empfohlene Reihenfolge lautet:

Dieses MVP-Setup dauerhaft dokumentieren.
Den aktuellen Roundtrip minimal und belastbar reparieren.
Repository- und Root-Namen final entscheiden.
Neue Root-Verzeichnisse parallel anlegen.
Git-Repositories und Remotes initialisieren.
Enterprise Architecture Foundation übernehmen.
Netzwerksolution Architecture als konkrete Reference Solution schneiden.
Engineering Platform als logisches CE/CI/CD-System schneiden.
Runtime-Struktur anlegen.
Capability Realization Module und ZIP-Verträge definieren.
Connector Management verallgemeinern.
Datenmodell des MVP konkretisieren und migrierbar beschreiben.
Golang-Backend, JavaScript-UI und MariaDB-Persistenz implementieren.
Dokumentationsartefakte in das neue System übernehmen.
HTML-Pipeline auf Artefaktbetrieb umstellen.
Automatisierung, Markdown-Extraktion und DB-Backups integrieren.
Testbetrieb mit den drei Referenzbenutzern aufnehmen.
Ergebnisse mit dem eingefrorenen Basissystem vergleichen.
Weitere Capabilities und Solutions schrittweise migrieren.

14. Nicht-Ziele des ersten MVP#

Der erste MVP soll ausdrücklich nicht

alle bisherigen Building Blocks vollständig implementieren,
alle bestehenden Dokumente sofort migrieren,
die alte Runtime sofort abschalten,
eine hochskalierbare verteilte Datenplattform einführen,
alle möglichen KI-Provider integrieren,
alle Connector-Typen vollständig implementieren,
oder eine endgültige Enterprise-Repository-Landschaft erzwingen.

Der MVP soll den gemeinsamen Modellansatz praktisch validieren und einen kleinen, real nutzbaren Kern bereitstellen.

15. Erfolgskriterien#

Das MVP-Setup gilt als erfolgreich umgesetzt, wenn

die neue Struktur parallel und ohne Zerstörung des Basissystems aufgebaut ist,
Architektur, Implementierung und Runtime getrennt sind,
die Engineering Platform dieselben Artefakt- und Beziehungsmodelle verwendet,
Connector Management externe Systeme einheitlich integrieren kann,
Capability-Realisierungen einzeln als ZIP bearbeitbar bleiben,
das erste UI Artefakte und Beziehungen verwalten kann,
MariaDB als operative Persistenz funktioniert,
Markdown und Datenbank-Dumps automatisiert erzeugt werden,
HTML aus verwalteten Artefakten publiziert wird,
die drei Referenzrollen praktisch verwendet werden können,
und der bestehende Roundtrip bis zur Ablösung zuverlässig als Migrationswerkzeug funktioniert.

16. Offene Entscheidungen vor dem harten Schnitt#

Vor der technischen Anlage der neuen Roots werden noch final bestätigt:

Die endgültigen Repository-Namen.
Die Remote-Namen und Hosting-Orte.
Ob netzwerksolution oder netzwerksolution-implementation als Implementierungsrepository verwendet wird.
Die endgültige Runtime-Struktur: environment-first oder solution-first.
Die genaue Grenze zwischen Enterprise Architecture und Netzwerksolution Metamodell.
Die Benennung von Capability Realization Modules.
Der genaue changed-only- und Modul-ZIP-Vertrag.
Die führende Quelle während der Übergangsphase zwischen Markdown und Datenbank.
Der minimale Umfang des Rich Text Editors.
Die erste Liste konkret zu implementierender Connectoren.

17. Architekturleitsätze#

Für alle folgenden Schritte gelten insbesondere:

Ein Konzept gehört auf die höchste Ebene, auf der seine Aussagen allgemeingültig sind.

Eine Architekturdomäne besitzt nur die Artefakte, für die sie fachlich verantwortlich ist.

Untere Ebenen verwenden allgemeine Modelle durch Referenzierung und definieren sie nicht konkurrierend neu.

Dauerhafte Definitionen und Implementierungsquellen gehören zur jeweiligen Architektur oder Plattform. Konkrete Installationen, Ausführungszustände und erzeugte Ergebnisse gehören zur Runtime.

Ein gemeinsames Git-Repository erzeugt keinen Monolithen. Modulgrenzen werden durch Verantwortlichkeiten, Schnittstellen, Abhängigkeiten und Tests geschützt.

Die bestehende Netzwerksolution bleibt als eingefrorene Baseline erhalten. Die neue Struktur wird parallel und kontrolliert aufgebaut.

Der erste MVP muss nutzbar, konsistent, nachvollziehbar und sicher rekonstruierbar sein. Er muss nicht bereits die vollständige Zielplattform darstellen.

18. Weiterführende Artefakte#

Das MVP-Setup baut auf Architekturartefakten der historischen SolutionArchitecture.zip auf. Die ursprünglichen historischen Pfade bleiben Provenienzangaben und werden nicht als Links auf nicht vorhandene Dateien materialisiert. Die heute führenden Enterprise-Einstiege sind:

Historische, lösungs- oder implementierungsspezifische Quellen wie Platform Data Models, Connector-Split-Reports, Persistence-Entscheidungen und Roundtrip-Entscheidungen werden bei ihrer Überführung der jeweils zuständigen nachgelagerten Architektur zugeordnet.

Nächster unmittelbarer Schritt#

Nach der Aufnahme dieses Dokuments wird der aktuell benötigte Roundtrip auf Basis des bestehenden Workspace-Standes repariert.

Die Reparatur wird gegen die in Abschnitt 11 beschriebenen Abnahmekriterien geprüft.

Erst danach beginnt die Anlage der neuen parallelen Root-Struktur.