Add architecture module map

docs/architektur/technical_architecture.md

@@ -0,0 +1,239 @@
+# Technische Architektur
+
+Stand: 2026-04-08
+Status: Verbindlicher Architektur-Master
+Dokumentklasse: normative
+
+## 1. Zweck und Geltung
+
+Dieses Dokument ist die verbindliche Architekturvorgabe fuer die Entwicklung hochmodularer Webportale in diesem Repository. Es steuert Analyse, Implementierung, Refactoring und Review durch Mensch und LLM.
+
+Es definiert verbindlich:
+
+- Modul-, Prozess-, Frontend-, API- und Datenbankgrenzen
+- Ownership und oeffentliche Schnittstellen
+- Standard-Scope fuer Analyse und Implementierung
+- Wiederverwendungs- und Redundanzregeln
+- Regeln fuer neue Module, Submodule und zentrale Bausteine
+
+Dieses Dokument ist kein Inventar konkreter Tabellen, Prozesse, Dateien oder Runtime-Artefakte. Solche Details liegen in den zustaendigen Modul-, Prozess- oder DB-Vertraegen.
+
+## 2. Architekturprinzipien
+
+### 2.1 Module
+
+Ein Modul ist ein fachlich oder technisch gekapselter Contract, nicht nur eine Verzeichnisstruktur.
+
+Verbindliche Regel:
+
+- jedes Modul besitzt genau eine klar abgegrenzte Primaerverantwortung
+- jedes Modul kapselt seine Domain-Logik, Datenzugriffe, externen Schnittstellen, internen Datenstrukturen und Speicherdetails
+- jedes Modul definiert eine explizite oeffentliche Schnittstelle fuer andere Module
+- jedes Modul besitzt definierte Owned Artefakte und Schreibrechte
+- interne Implementierungen anderer Module duerfen nicht direkt genutzt werden
+- jede Modulgrenze muss als potenzielle spaetere Service-Grenze behandelbar bleiben
+
+### 2.2 Prozesse
+
+Ein Prozess ist ein sequenzieller Hauptablauf innerhalb genau eines owning Hauptmoduls.
+
+Verbindliche Regel:
+
+- ein Hauptmodul besitzt beliebig viele Hauptprozesse; jeder Hauptprozess gehoert genau einem Hauptmodul
+- ein Hauptprozess darf Submodule desselben Hauptmoduls nutzen
+- fachliche Hauptprozesse ueber Hauptmodulgrenzen hinweg sind nicht zulaessig
+- Batching, Parallelisierung, Retry, Resume, Fehlerklassifikation, Statusermittlung und Ergebnisvertrag gehoeren in den owning Prozessvertrag
+- zusaetzliche harte Schreib-, Feld- oder Datenbankschranken sind nur zulaessig, wenn sie explizit im Prozess- oder DB-Vertrag festgelegt sind
+
+
+
+### 2.3 Implementierung
+
+Module, Prozesse und Sub-Prozesse sind technisch so scharf wie moeglich zu trennen.
+
+Verbindliche Regel:
+
+- jedes Modul besitzt eine interne API oder Zugriffsschicht
+- Cross-Modul-Kommunikation erfolgt nur ueber definierte Modul-Schnittstellen
+- direkte Zugriffe auf interne Implementierungen oder Daten anderer Module sind verboten
+- Module, Prozesse und Sub-Prozesse muessen getrennt entwickelbar, testbar, ausrollbar, ueberwachbar, debugbar und optimierbar sein
+- technische Kopplung zwischen Prozessen und Sub-Prozessen ist auf das notwendige Minimum zu reduzieren
+- Module duerfen keine impliziten Abhaengigkeiten besitzen, die eine spaetere Extraktion verhindern
+
+### 2.4 Frontend
+
+Das Frontend ist bewusst minimalistisch. Ziel ist eine kleine Zahl konsistenter, wiederverwendbarer UI-Bausteine statt vieler seiten- oder feature-spezifischer Sonderkomponenten.
+
+Verbindliche Regel:
+
+- Seiten und Views komponieren Daten, Layouts und Komponenten, erzeugen aber keine Fachlogik
+- UI-Komponenten duerfen keine fachliche Primaerlogik, fachliche Dateninterpretation oder eigenstaendige Fachwahrheit besitzen
+- fachliche UI-Komponenten, fachliche Darstellungsregeln und fachlich interpretierende UI-Logik gehoeren zum owning Fachmodul
+- fachlich neutrale UI-Komponenten, Layout-Komponenten, Formatierungshelfer, Interaktionsmuster und Frontend-Utilities gehoeren nach `shared`
+- neue oder geaenderte Frontend-Komponenten muessen zuerst gegen bestehende Komponenten, Patterns und `shared`-Bausteine geprueft werden
+- Varianten bestehender Komponenten sind ueber Props, Konfiguration oder dokumentierte Erweiterungspunkte umzusetzen, nicht durch Copy-Paste
+- Karten, Tabellen, Filter, Tabs, Buttons, Statusanzeigen, Ladezustaende, Empty States, Fehlermeldungen und Detailansichten sind als wiederverwendbare Patterns zu behandeln
+- seitenlokale Sonderkomponenten sind nur zulaessig, wenn sie nachweislich nicht sinnvoll wiederverwendbar sind
+- API-Responses duerfen frontendnah komponiert sein, aber keine Fachlogik aus dem owning Modul in API oder Frontend verschieben
+
+## 3. Modulmodell
+
+### 3.1 Zulaessige Modulbereiche
+
+Fachliche Hauptmodule:
+
+- `zu definieren
+
+Technische Modulbereiche:
+
+- `system`
+- `shared`
+
+Verbindliche Regel:
+
+- fachliche Hauptmodule besitzen Business-Logik und fachliche Ownership
+- `system` enthaelt nur technische Runtime-, Start-, Trigger- und Laufzeitlogik
+- `shared` enthaelt nur fachlich neutrale, wiederverwendbare technische Bausteine
+- konkrete Submodule, Prozesse, Artefakte und Schnittstellen werden in Modulvertraegen dokumentiert, nicht in diesem Architektur-Master
+
+### 3.2 `shared`
+
+`shared` ist der zentrale technische Querschnittsbereich.
+
+Verbindliche Regel:
+
+- `shared` darf keine Business-Logik, Fachwahrheit oder primaere fachliche Ownership besitzen
+- `shared` darf Services, Komponenten, Helper, technische Schnittstellen, UI-nahe und API-nahe Bausteine bereitstellen
+- ein Baustein gehoert nur nach `shared`, wenn er fachlich neutral ist und keine Verantwortung eines Fachmoduls uebernimmt
+- fachliche Regeln, Dateninterpretation, Statuslogik und Entscheidungen bleiben im owning Fachmodul
+- technische Querschnittslogik ohne fachlichen Inhalt muss in `shared` oder einem dort dokumentierten zentralen Baustein liegen, sobald Wiederverwendung ueber mehr als eine Stelle absehbar ist
+
+### 3.3 `admin`
+
+`admin` ist kein Hauptmodul und besitzt keine fachliche Ownership.
+
+Verbindliche Regel:
+
+- Admin-Funktionen sind nur Bedienoberflaechen auf bestehende Hauptmodule
+- Admin-spezifische Fachlogik liegt im owning Hauptmodul
+- ein separates fachliches Modul `admin` ist nicht zulaessig
+
+### 3.4 `public/api/`
+
+`public/api/` ist die HTTP-Service- und Kompositionsschicht des modularen Monolithen.
+
+Verbindliche Regel:
+
+- `public/api/` besitzt keine fachliche Primaerverantwortung
+- `public/api/` darf Modul- oder Submodul-Schnittstellen fuer konkrete Frontend-User-Stories zusammensetzen
+- `public/api/` bleibt duenn und enthaelt nur HTTP-nahe und technische Kompositionslogik
+- fachliche Ownership darf nicht aus Modulen in `public/api/` wandern
+
+## 4. Datenbankgrenze
+
+Die Plattform nutzt aktuell genau eine gemeinsame Datenbank. Diese gemeinsame Datenbank hebt Modul- und Ownership-Grenzen nicht auf.
+
+Verbindliche Regel:
+
+- jede Tabelle, View, materialisierte View und DB-Funktion besitzt genau eine primaere Ownership
+- primaere Ownership folgt genau einem Hauptmodul oder einem technischen Shared-Bereich
+- nur das owning Modul definiert Struktur, Write-Logik, Constraints und fachliche Semantik eines DB-Artefakts
+- direkte Cross-Modul-Writes in fremde Owned Tabellen sind verboten
+- andere Module duerfen fremde Artefakte nur ueber definierte Schnittstellen des owning Moduls nutzen
+- physische DB-Splits sind kein aktueller Standard und beduerfen einer expliziten Architekturentscheidung
+
+Operative DB-Referenz:
+
+`docs/architektur/database/module_db_ownership.md`
+
+Verbindliche Regel:
+
+- konkrete DB-Artefaktlisten gehoeren in die DB-Ownership-Dokumentation, nicht in diesen Architektur-Master
+- bei Analyse, Refactoring und Implementierung wird der DB-Scope zuerst ueber Modul plus Owned DB-Artefakte bestimmt
+- fremde DB-Artefakte duerfen nur bei deklarierter Leseabhaengigkeit, FK-Beziehung oder Integrationspruefung in den Scope aufgenommen werden
+
+## 5. Dokumentation und Lesescope
+
+Aktive Dokumentation ist komponentennah.
+
+Verbindliche Regel:
+
+- aktive Modul- und Submodul-Dokumentation liegt unter `docs/modules/<modul>/...`
+- aktive technische Shared-Dokumentation liegt unter `docs/modules/shared/...`
+- technische Runtime-Dokumentation liegt unter `docs/modules/system/...`
+- fachliche Hauptprozesse liegen innerhalb des owning Modulbaums
+- historische oder abgeloeste Dokumentation liegt ausserhalb des aktiven Modulbaums
+- `docs/architektur/technical_architecture.md` bleibt der einzige aktive Architektur-Master
+
+Standard-Lesescope:
+
+- Arbeit an einem Modul: `docs/architektur/technical_architecture.md` plus `docs/modules/<modul>/...`
+- Arbeit an einem Submodul: `docs/architektur/technical_architecture.md` plus `docs/modules/<modul>/<submodul>/...`
+- `docs/modules/shared/...`: nur bei betroffener Shared-Schnittstelle oder moeglicher Wiederverwendung
+- `docs/modules/system/...`: nur bei Runtime-, Queue-, Scheduler-, Trigger- oder Supervisor-Themen
+- andere Module: nur bei explizitem Integrationsbedarf
+
+## 6. Wiederverwendung und Redundanzverbot
+
+Vor jeder Aenderung an App, Frontend, UI-Komponenten, UI-Patterns, API, Prozesslogik, Datenzugriff, Infrastruktur oder Dokumentation ist Wiederverwendung vor Neuerstellung zu pruefen.
+
+Ziel ist eine Architektur ohne redundante Fachlogik, technische Inselloesungen, doppelte UI-Komponenten oder mehrfach gepflegte Varianten desselben Musters.
+
+Verbindliche Regel:
+
+- zuerst bestehende Muster, Komponenten, Services, Modul-Schnittstellen und `shared`-Bausteine pruefen
+- vorhandene passende Muster muessen wiederverwendet, erweitert oder als zentrale Schnittstelle bereitgestellt werden
+- fachliche Inhalte gehoeren immer in das owning Fachmodul und werden von dort ueber definierte Schnittstellen bereitgestellt
+- fachliche Logik darf nicht in `shared`, `public/api/`, `admin`, Skripte oder fachfremde Bereiche ausgelagert oder dupliziert werden
+- fachlich neutrale technische Logik gehoert nach `shared`, sofern sie wiederverwendbar ist oder Wiederverwendung absehbar ist
+- Frontend-Darstellung, Interaktionslogik, Layout, Formatierung und Zustandsdarstellung sind als bestehende oder neue zentrale UI-Komponenten beziehungsweise UI-Patterns in `shared` zu pruefen
+- neue `shared`-Bausteine sind nur zulaessig, wenn sie keine Fachwahrheit enthalten, keine fachliche Primaerverantwortung uebernehmen und wiederverwendbar sind
+- technische Querschnittsbausteine duerfen Module entkoppeln, aber keine fachlichen Entscheidungen aus owning Modulen herausziehen
+- neue Loesungen sind nur zulaessig, wenn kein passendes bestehendes Muster, keine passende Modul-Schnittstelle und kein geeigneter `shared`-Baustein existiert
+- Quickfixes, Workarounds, Copy-Paste-Varianten, seitenlokale UI-Duplikate und isolierte Sonderlogik fuer Einzelstellen sind verboten
+- Redundanzvermeidung muss bei Analyse, Umsetzung, Review und Refactoring aktiv nachgewiesen werden koennen
+
+## 7. Verbotene Strukturen
+
+Nicht zulaessig sind:
+
+- Module als reine Ordner ohne Contract
+- direkte Cross-Modul-Zugriffe auf DB-Tabellen, interne Implementierungen oder Daten anderer Module
+- versteckte oder implizite Modulabhaengigkeiten
+- Vermischung mehrerer Primaerverantwortungen innerhalb eines Moduls
+- parallele Fachlogik ausserhalb des owning Moduls
+- redundante fachliche, technische oder UI-Loesungen, obwohl ein bestehendes Modul, eine Schnittstelle, ein Pattern oder ein `shared`-Baustein erweitert werden koennte
+- neue generische Frameworks oder Orchestrator-Umbauten ohne explizite Architekturentscheidung
+- implizite Schutz-, Schreib- oder Datenbankschranken ohne Prozess- oder DB-Vertrag
+
+## 8. Erweiterungsregeln
+
+Neue Hauptmodule, Submodule oder zentrale Bausteine duerfen nur eingefuehrt werden, wenn bestehende Strukturen die Verantwortung nicht sauber tragen koennen.
+
+Prueffragen vor jeder Erweiterung:
+
+1. Welches bestehende Hauptmodul ist primaer betroffen?
+2. Reicht eine neue Datei, ein neues Submodul oder eine neue Schnittstelle im owning Hauptmodul aus?
+3. Handelt es sich um fachlich neutrale Wiederverwendung, die nach `shared` gehoert?
+4. Entsteht wirklich eine neue Primaerverantwortung mit eigenen Owned Artefakten und Schreibrechten?
+5. Bleibt der Handshake zum Rest des Systems auf minimale Scope-Identifier begrenzt?
+6. Reduziert der neue Schnitt Kopplung und Redundanz, statt sie zu erhoehen?
+
+Verbindliche Regel:
+
+- neue Hauptmodule sind nur zulaessig, wenn eine neue fachliche oder technische Primaerverantwortung entsteht, die nicht sauber in `company`, `ratings`, `groups`, `lists`, `system` oder `shared` aufgeht
+- neue Submodule sind nur zulaessig, wenn innerhalb eines bestehenden Hauptmoduls eine klar isolierbare Verantwortung mit eigener Schnittstelle entsteht
+- neue Prozess- und Sub-Prozess-Dokumente werden im owning Modulpfad angelegt und folgen `component.subcomponent.process_name`
+- `admin`, `public/api/`, `scripts/` oder `lib/` begruenden kein neues fachliches Hauptmodul
+- Bequemlichkeit, Dateigroesse oder kurzfristiger Umbauaufwand rechtfertigen kein neues Hauptmodul
+- vor jeder normativen Architektur- oder Modulerweiterung muss dieses Dokument aktualisiert werden
+
+## 9. Aenderungsregel
+
+Jede strukturelle Aenderung an Hauptmodulen, Modulgrenzen, Prozesszuordnungen, Frontend-Prinzipien, API-Grenzen, DB-Ownership oder primaeren Ownership-Prinzipien muss zuerst in diesem Dokument normativ festgelegt und danach in Detaildokumenten nachgezogen werden.
+
+Verbindlich ist:
+
+- `docs/technical_architecture.md` ist der einzige aktive Architektur-Master des Repositories
+- andere Dokumente duerfen diese Architektur erklaeren, anwenden oder historisieren, aber keine konkurrierende Master-Struktur definieren
+- konkrete Inventare wie Tabellenlisten, Submodullisten, Prozesslisten oder Runtime-Artefakte werden in Detaildokumenten gepflegt und nicht hier dupliziert