Netzwerksolution Documentation Report

MVP-001-MODULARITY-RULES

MVP-001 – Modularitäts- und Abhängigkeitsregeln#

Zweck#

Diese Regeln verhindern, dass die Engineering Platform trotz gemeinsamer Go-Binary und gemeinsamer Webanwendung zu einem ungeordneten Monolithen wird. Sie gelten ab dem ersten Implementierungscommit.

Grundsatz#

Ein gemeinsames Deployment ist zulässig. Vermischte fachliche Verantwortung ist nicht zulässig.

Ein ist eine fachlich und technisch abgegrenzte Einheit mit eigenem Contract, eigenen Modellen, eigenen Use Cases, veröffentlichten Ports und eigenen Tests.

Verbindliche Regeln#

MOD-001 – Fachliche Ownership#

Jedes fachliche Konzept, jede Geschäftsregel und jedes Persistenzobjekt besitzt genau einen verantwortlichen Building Block.

Andere Blocks dürfen dieses Konzept verwenden, aber nicht parallel definieren oder seine Regeln umgehen.

MOD-002 – Keine direkten Fremdzugriffe#

Ein Building Block darf nicht direkt auf interne Packages, Frontend-Interna oder Tabellen eines anderen Building Blocks zugreifen.

Zulässige Kommunikation erfolgt über:

MOD-003 – Keine zyklischen Abhängigkeiten#

Abhängigkeiten zwischen Building Blocks müssen gerichtet und azyklisch sein.

Ein Pull Request beziehungsweise Build mit neuem Zyklus ist nicht promotionsfähig.

MOD-004 – Fachlogik vor Adaptern#

Fachregeln liegen im zuständigen Domain- oder Application-Modul, nicht in:

Adapter übersetzen zwischen Verträgen und technischen Systemen.

MOD-005 – Persistenzhoheit#

Der Persistence Building Block stellt technische Infrastruktur bereit. Die fachliche Hoheit über Schema und Datenregeln verbleibt beim zuständigen Fachblock.

Eine gemeinsame MariaDB bedeutet nicht, dass jeder Block jede Tabelle lesen oder schreiben darf.

MOD-006 – Frontend folgt denselben Grenzen#

Jeder fachliche Backend-Block besitzt ein korrespondierendes Frontend-Modul, soweit er UI-Verantwortung hat.

Frontend-Module dürfen fremde Zustände nicht durch globale, unstrukturierte Stores oder direkte interne Imports verändern.

MOD-007 – UI und Backend bleiben getrennt#

Das Frontend greift ausschließlich über veröffentlichte Backend-Verträge auf fachliche Funktionen zu.

Direkter Zugriff auf MariaDB, , Dateisystem, Translation , Engineering Tools oder Runtime-Verzeichnisse ist verboten.

MOD-008 – Gemeinsame Bibliotheken bleiben klein#

Ein gemeinsamer Bereich darf nur technisch allgemeingültige Elemente enthalten, beispielsweise:

Fachliche Modelle, Statuswerte und Geschäftsregeln dürfen nicht in einem globalen common, shared oder utils versteckt werden.

MOD-009 – Contracts sind versioniert#

Veröffentlichte APIs, Events und Ports besitzen dokumentierte Contracts. Inkompatible Änderungen werden bewusst versioniert oder migriert.

MOD-010 – Eigene Tests je Building Block#

Jeder Building Block besitzt mindestens:

End-to-End-Tests ergänzen diese Tests, ersetzen sie aber nicht.

MOD-011 – Traceability ist Pflicht#

Jeder neue Building Block und jede wesentliche Änderung referenziert:

Nicht rückverfolgbare technische Funktionalität gehört nicht in MVP-001.

MOD-012 – Extrahierbarkeit#

Ein Building Block muss so aufgebaut sein, dass er später technisch extrahiert werden kann, ohne sein Fachmodell neu zu schreiben.

Dazu gehören insbesondere:

Eine tatsächliche Extraktion ist im nur bei belegtem Betriebs- oder Skalierungsbedarf vorgesehen.

MOD-013 – Keine vorschnellen Microservices#

Ein Building Block ist nicht automatisch ein deploybarer Service.

Ein eigener Prozess oder Container wird nur eingeführt, wenn mindestens einer der folgenden Gründe dokumentiert ist:

MOD-014 – Änderungen über Use Cases#

Schreibende Operationen laufen über explizite Application Use Cases beziehungsweise Commands. UI, HTTP-Handler und Worker dürfen fachliche Zustände nicht direkt verändern.

MOD-015 – Auditierbare Blockgrenzen#

Blockübergreifende schreibende Aktionen müssen Korrelation, Akteur und Ursprung erhalten. Sie müssen durch Audit & Traceability nachvollziehbar sein.

MOD-016 – Background Jobs sind fachlich zugeordnet#

Ein Worker führt einen Auftrag im Namen des fachlich zuständigen Blocks aus. Ein generischer Worker darf keine fachlichen Entscheidungen übernehmen.

Beispiele:

MOD-017 – Engineering Tools bleiben außerhalb der Fachlogik#

Engineering Tools führen Packaging, Validierung, Repositoryzugriff und technische Materialisierung aus.

Die Engineering Platform entscheidet fachlich, wann ein Roundtrip gestartet, geprüft, angenommen oder abgelehnt wird. Engineering Tools dürfen diese Entscheidung nicht treffen.

MOD-018 – Mehrsprachigkeit ist blockübergreifend, aber nicht global vermischt#

Diese vier Verantwortungen dürfen nicht zu einem unspezifischen i18n-Block vermischt werden.

Go-Package-Regeln#

Für jeden fachlichen Go-Block ist folgende Grundstruktur zulässig:

internal/<block>/
                ├── domain/
                ├── application/
                ├── ports/
                ├── adapters/
                └── transport/

Nicht jeder Block muss sofort alle Unterordner besitzen. Leere Schichten werden nicht auf Vorrat erzeugt.

Verbindlich ist jedoch:

JavaScript-Modul-Regeln#

Für jeden UI-relevanten Block ist folgende Grundstruktur zulässig:

src/<block>/
                ├── api/
                ├── components/
                ├── pages/
                ├── state/
                ├── i18n/
                └── tests/

Auch hier werden nur tatsächlich benötigte Bereiche angelegt.

Ein Frontend-Modul veröffentlicht eine kleine explizite Oberfläche. Tiefenimports in interne Verzeichnisse anderer Module sind nicht zulässig.

Prüfung#

Die Regeln sollen schrittweise automatisiert werden, unter anderem durch:

Ownership- und Dependency-Nachweis#

Die Regeln MOD-001 bis MOD-018 werden für den aktuellen MVP-Scope durch die konkretisiert. Die Matrix ist keine zweite Definition der Building Blocks, sondern die prüfbare Zuordnung von Owner, veröffentlichter Grenze und zulässiger direkter Abhängigkeit. Änderungen an Kernverantwortungen benötigen eine explizite Architekturentscheidung.

↑