Zum Inhalt

Architektur-Entscheidungen zur App Plattform

🧠 Entscheidungen

Stand: 2026-11-10 Status aller ADRs: Vorgeschlagen (wird mit dem Review durch den Product Owner auf Akzeptiert gesetzt)

Hinweis zum Format: Jedes ADR enthält neben Begründung und Konsequenzen einen Block Regeln (verbindlich). Dieser Block ist die knappe, prüfbare Fassung für Entwickler und KI-Agenten und wird 1:1 in die AGENTS.md übernommen. Begründung und Konsequenzen dienen dem Verständnis und zukünftigen Entscheidungen.


ADR-001: Nx-Monorepo und modularer Monolith

Entscheidung:

Die Anwendung wird als Nx-Monorepo aufgebaut und folgt dem Architekturansatz eines modularen Monolithen. Die fachlichen Module werden klar voneinander abgegrenzt. Die Einhaltung der Modulgrenzen wird durch automatisierte Lint-Regeln sichergestellt.

Begründung:

  • Ein gemeinsames Repository erleichtert die Entwicklung und Wartung zusammengehöriger Frontend- und Backend-Komponenten.
  • Ein modularer Monolith reduziert die betriebliche Komplexität gegenüber einer Microservice-Architektur.
  • Klare Modulgrenzen ermöglichen eine fachliche Trennung und reduzieren unerwünschte Abhängigkeiten.
  • Automatisierte Regeln verhindern, dass Architekturvorgaben im Laufe der Entwicklung aufgeweicht werden.
  • Die Architektur ermöglicht bei Bedarf eine spätere Ausgliederung einzelner Module.

Konsequenzen:

  • Alle Anwendungskomponenten werden innerhalb eines gemeinsamen Nx-Workspace verwaltet.
  • Fachliche Module müssen ihre definierten Schnittstellen einhalten (siehe ADR-016).
  • Direkte Abhängigkeiten zwischen Modulen außerhalb der erlaubten Schnittstellen sind nicht zulässig.
  • Architekturregeln werden Bestandteil der CI-Pipeline.
  • Änderungen an gemeinsamen Bibliotheken können mehrere Module gleichzeitig betreffen.

Regeln (verbindlich):

  • Jedes Fachmodul (core, finance, realestate, fitness, kids, inventory) ist eine eigene Nx-Bibliothek bzw. ein eigener Bibliotheksverbund mit Tags (scope:<modul>, type:<feature|data|ui|util>).
  • Die Nx-Modulgrenzen-Regel (@nx/enforce-module-boundaries) ist aktiv und schlägt in der CI fehl, wenn sie verletzt wird.
  • Fachmodule dürfen von core und shared abhängen, core und shared dürfen NICHT von Fachmodulen abhängen.
  • Fachmodule dürfen NICHT direkt voneinander importieren (Kommunikation siehe ADR-016).
  • Zirkuläre Abhängigkeiten sind verboten.
  • Lint-Regeln dürfen NICHT per Kommentar (eslint-disable) für Modulgrenzen umgangen werden.

ADR-002: Angular-Shell und lazy geladene Feature-Module

Entscheidung:

Die Anwendung verwendet eine zentrale Angular-Shell (eine einzige App), in welche die einzelnen Feature-Module integriert werden. Die Feature-Module werden mittels Lazy Loading geladen. Die Verfügbarkeit von Modulen und Funktionen wird über Entitlements gesteuert. Die Shell unterstützt rollenabhängige Layouts und Themes (z. B. vereinfachte Oberfläche für Kinder).

Begründung:

  • Eine zentrale Shell stellt eine einheitliche Benutzeroberfläche und Navigation sicher.
  • Lazy Loading reduziert die initiale Ladezeit und den Ressourcenbedarf.
  • Die modulare Struktur ermöglicht eine unabhängige Entwicklung fachlicher Funktionsbereiche.
  • Entitlements erlauben eine flexible Freischaltung von Funktionen abhängig von den Berechtigungen und gebuchten Leistungen einer Organisation.
  • Die Architektur schafft eine Grundlage für unterschiedliche Produktvarianten und Lizenzmodelle.
  • Rollenabhängige Layouts erlauben es, innerhalb einer App sehr unterschiedliche Zielgruppen (Unternehmen, Mieter, Kinder) zu bedienen.

Konsequenzen:

  • Gemeinsame Layout- und Navigationskomponenten werden zentral in der Shell bereitgestellt.
  • Feature-Module müssen unabhängig von anderen Feature-Modulen ladbar sein.
  • Modulzugriffe und Navigation werden anhand der verfügbaren Entitlements gesteuert.
  • Die Backend-Autorisierung muss unabhängig von der Frontend-Steuerung erfolgen.
  • Nicht freigeschaltete Funktionen dürfen nicht allein durch Manipulation des Frontends zugänglich werden.
  • Die Shell stellt Mechanismen für Theming und rollenabhängige Layout-Varianten bereit, bevor das erste Fachmodul sie benötigt.

Regeln (verbindlich):

  • Es gibt genau eine Angular-Anwendung (Shell). Fachmodule sind lazy geladene Routen-Bibliotheken.
  • Jedes Fachmodul registriert sich über eine definierte Modul-Registrierung (Id, benötigtes Entitlement, Navigationseinträge, Permissions).
  • Navigation und Routen werden aus den Entitlements der aktiven Organisation aufgebaut. Ein Route-Guard prüft das Entitlement zusätzlich.
  • Das Frontend DARF NICHT als alleinige Zugriffskontrolle dienen: Jeder Backend-Endpunkt prüft Entitlement und Permission selbst.
  • Layout-Varianten werden über das Theming-System der Shell umgesetzt, NICHT über Kopien von Komponenten.

ADR-003: Einheitliche fachliche Terminologie

Entscheidung:

Für die zentralen fachlichen Konzepte werden intern folgende verbindliche Begriffe verwendet. Diese können sich je nach App-Kontext auf unterschiedliche Texte mappen:

  • Organization: Organisation bzw. Mandant innerhalb des Systems (je nach Kontext z. B. Firma, Familie, Hausverwaltung, Eigentümer).
  • Membership: Zugehörigkeit eines Benutzers zu einer Organisation, inklusive Rollen.
  • Lessee: Mieter bzw. mietende Partei. Ein Lessee ist ein fachliches Objekt des Immobilienmoduls (mietende Partei mit Mietverhältnis) und KEIN Benutzerkonto.
  • AccessGrant: Explizit gewährte Zugriffsberechtigung auf eine Ressource oder einen Funktionsbereich, entweder von einer Organisation an eine andere Organisation oder von einer Organisation an einen Benutzer ohne Membership (z. B. Mieter).
  • User: Benutzeridentität, verknüpft mit dem Identity Provider.
  • Role: Benannte Bündelung von Permissions innerhalb einer Organisation.
  • Permission: Feingranulare, modulbezogene Berechtigung (siehe ADR-006).
  • Entitlement: Freischaltung eines Moduls oder einer Funktion für eine Organisation.
  • Module: Fachlicher Funktionsbereich der Anwendung (z. B. finance, realestate).

Begründung:

  • Eine einheitliche Terminologie verhindert Missverständnisse zwischen Entwicklung, Fachbereich und Architektur.
  • Die Begriffe bilden unterschiedliche fachliche Konzepte ab und vermeiden deren Vermischung.
  • Insbesondere die Trennung zwischen einer Benutzerzugehörigkeit (Membership), einer mietenden Partei (Lessee) und einer Zugriffsberechtigung (AccessGrant) ist für das Berechtigungsmodell wesentlich.
  • Der englische Begriff "Tenant" ist mehrdeutig (Mandant oder Mieter) und wird daher im Code nicht verwendet.
  • Einheitliche Begriffe erleichtern die Kommunikation zwischen menschlichen Entwicklern und KI-Agenten.

Konsequenzen:

  • Die definierten Begriffe werden in Code, Datenbankmodellen, APIs und Dokumentation verwendet.
  • Abweichende oder synonym verwendete Bezeichnungen sind zu vermeiden.
  • Neue fachliche Konzepte müssen in die zentrale Terminologie aufgenommen werden.
  • Die Begriffe bilden die Grundlage für das gemeinsame Domänenmodell.
  • Die Bezeichnungen in den Translation Files sind hiervon unberührt und können von der jeweiligen Fachabteilung frei festgelegt werden.
  • Ein Mieter mit Portalzugang erhält ein normales Benutzerkonto, das per AccessGrant mit seinem Lessee-Datensatz verknüpft ist. Er sieht nur seine Einheit, seine Dokumente und seine Kommunikation und besitzt keine eigene Organisation. Mieter ohne Portalzugang existieren ausschließlich als Lessee-Datensatz.
  • Eigentümer und Hausverwaltung sind jeweils eigene Organisationen. Der Zugriff der Hausverwaltung auf Objekte des Eigentümers erfolgt über AccessGrant. Ist Eigentümer und Hausverwaltung dieselbe Person, existiert nur eine Organisation und kein AccessGrant.

Regeln (verbindlich):

  • Im Code, in Datenbank, API und Dokumentation wird "Tenant" NICHT verwendet. Es heißt Organization (Mandant) bzw. Lessee (Mieter).
  • Eine Ressource gehört immer genau einer Organisation (organization_id).
  • Zugriff durch andere Organisationen erfolgt ausschließlich über AccessGrant, NICHT über Duplizierung von Daten oder Sonderfelder.
  • Ein Lessee ist kein User. Die Verknüpfung erfolgt über AccessGrant.
  • Neue Kernbegriffe werden zuerst in dieses Glossar aufgenommen, bevor sie im Code verwendet werden.
  • UI-Texte stammen ausschließlich aus Translation Files (siehe ADR-012) und dürfen von den Domänenbegriffen abweichen.

ADR-004: Keycloak für Authentifizierung und anwendungsseitige Autorisierung

Entscheidung:

Keycloak wird als zentraler Identity Provider für die Authentifizierung eingesetzt. Die Kommunikation erfolgt über OpenID Connect (OIDC). Die fachliche Autorisierung und Prüfung von Berechtigungen wird innerhalb der Anwendung umgesetzt. Das Token enthält ausschließlich Identitätsinformationen. Die aktive Organisation wird pro Request explizit übermittelt und serverseitig gegen die Membership geprüft.

Begründung:

  • Keycloak stellt eine etablierte und zentral verwaltbare Lösung für die Authentifizierung bereit.
  • OIDC ermöglicht eine standardisierte Integration und reduziert die Abhängigkeit von einem konkreten Identity Provider.
  • Die Trennung zwischen Authentifizierung und Autorisierung ermöglicht eine unabhängige Weiterentwicklung beider Bereiche.
  • Fachliche Berechtigungen hängen von anwendungsspezifischen Konzepten wie Organisationen, Memberships und Entitlements ab.
  • Die Anwendung behält dadurch die vollständige Kontrolle über ihre fachlichen Zugriffsregeln.
  • Da ein Benutzer mehreren Organisationen angehören kann, ist die Organisation keine Eigenschaft der Identität, sondern des einzelnen Requests.
  • Weitere Services sollen künftig in dasselbe SSO integriert werden.

Konsequenzen:

  • Keycloak übernimmt Benutzeranmeldung, Identitätsverwaltung und Token-Ausstellung (inklusive MFA und Passkeys).
  • Die Anwendung validiert die erhaltenen Tokens.
  • Fachliche Berechtigungen werden innerhalb der Anwendung ermittelt und geprüft.
  • Keycloak-Rollen werden nicht als alleinige Grundlage für fachliche Berechtigungsentscheidungen verwendet.
  • Die Anwendung muss die Zuordnung zwischen Benutzeridentität und fachlichen Benutzer- bzw. Organisationsdaten verwalten.
  • Das Realm-Design muss Logins für Kinder ohne E-Mail-Adresse (Benutzername und PIN, durch Eltern verwaltet) unterstützen.
  • Es werden ausschließlich Standard-OIDC-Funktionen genutzt, damit ein Wechsel des Identity Providers möglich bleibt.

Regeln (verbindlich):

  • Der Schlüssel zwischen Keycloak und App-Benutzer ist der sub-Claim. Der App-User wird beim ersten Login angelegt.
  • Tokens enthalten KEINE Organisation und KEINE fachlichen Permissions als Entscheidungsgrundlage.
  • Die aktive Organisation wird pro Request über den Header X-Organization-Id übergeben und serverseitig gegen die Membership bzw. den AccessGrant geprüft. Dem Client wird NICHT vertraut.
  • Token-Validierung (Signatur, Issuer, Audience, Ablauf) erfolgt in einem zentralen Guard. Einzelne Endpunkte validieren Tokens NICHT selbst.
  • Kein Modul spricht direkt mit der Keycloak-Admin-API. Dies erfolgt ausschließlich über einen zentralen Service im core.
  • Passwörter und Tokens werden NICHT geloggt und NICHT im Frontend im localStorage abgelegt.

ADR-005: Mandantenisolation durch zentrales Scoping und PostgreSQL RLS

Entscheidung:

Die Mandantenisolation wird durch eine Kombination aus zentralem Organization-Scoping innerhalb der Anwendung und Row Level Security (RLS) auf PostgreSQL-Ebene umgesetzt. Die RLS-Policies berücksichtigen sowohl die eigene Organisation als auch gültige AccessGrants. Automatisierte Isolationstests sind verpflichtender Bestandteil der Test-Suite.

Begründung:

  • Die Isolation von Mandantendaten ist eine zentrale Sicherheitsanforderung der Anwendung.
  • Zentrales Scoping stellt sicher, dass der Organisationskontext konsistent innerhalb der Anwendung berücksichtigt wird.
  • PostgreSQL RLS bietet eine zusätzliche Sicherheitsebene direkt auf Datenbankebene.
  • Die Kombination beider Mechanismen reduziert das Risiko, dass fehlerhafte oder vergessene Filter zu mandantenübergreifenden Datenzugriffen führen.
  • RLS wirkt nur unter bestimmten Bedingungen (u. a. DB-Rolle, FORCE, Kontextsetzung). Diese Bedingungen müssen daher als Regeln festgeschrieben und automatisiert geprüft werden.
  • Automatisierte Isolationstests machen Sicherheitsverletzungen frühzeitig erkennbar.

Konsequenzen:

  • Datenbankabfragen müssen grundsätzlich im Kontext einer eindeutig bestimmten Organisation ausgeführt werden.
  • Der Organisationskontext wird zentral ermittelt und an die Datenbankzugriffe weitergegeben.
  • Die PostgreSQL-RLS-Policies müssen für alle mandantenbezogenen Tabellen definiert und gepflegt werden.
  • Datenbankverbindungen und Transaktionen müssen den Organisationskontext zuverlässig setzen und zurücksetzen.
  • Integrationstests müssen insbesondere den unberechtigten Zugriff auf Daten anderer Organisationen prüfen.
  • Änderungen an Organisationsmodellen oder Datenbankstrukturen erfordern eine Überprüfung der Isolation.
  • Die Anwendung benötigt zwei Datenbankrollen mit unterschiedlichen Rechten (Laufzeit und Migration).

Regeln (verbindlich):

  • Die Anwendung verbindet sich zur Laufzeit mit einer eigenen DB-Rolle, die weder Superuser ist noch Owner der Tabellen. Migrationen laufen mit einer separaten Rolle. (Superuser und Owner umgehen RLS.)
  • Jede mandantenbezogene Tabelle hat eine Spalte organization_id (NOT NULL) und ENABLE sowie FORCE ROW LEVEL SECURITY.
  • Der Kontext wird pro Transaktion mit SET LOCAL (bzw. set_config(..., true)) gesetzt, NIE auf Session-Ebene (Connection-Pool).
  • Fehlt der Kontext, liefern die Policies KEINE Zeilen (fail closed).
  • Die Policies berücksichtigen AccessGrants (eigene Organisation ODER gültige Freigabe mit passender Berechtigung).
  • Jeder Request mit Datenbankzugriff läuft in einer Transaktion mit gesetztem Kontext. Direkte Datenbankzugriffe am Kontext vorbei (z. B. eigener DataSource, Raw Queries ohne Kontext) sind verboten.
  • Eine automatische Isolationstest-Suite iteriert über alle Tabellen mit organization_id und schlägt fehl, wenn für eine Tabelle RLS, FORCE oder eine Policy fehlt. Zusätzlich gibt es Tests für Fremdzugriff über API und über AccessGrant.
  • Jede Migration, die eine mandantenbezogene Tabelle anlegt, enthält die zugehörigen RLS-Statements.

ADR-006: Modulbezogenes Permission-Modell

Entscheidung:

Berechtigungen werden als modulbezogene Permission-Strings definiert. Die Benennung folgt einer einheitlichen hierarchischen Struktur, beispielsweise finance:booking:write. Rollen dienen ausschließlich dazu, mehrere Permissions zu einer fachlich sinnvollen Berechtigungsgruppe zusammenzufassen.

Begründung:

  • Ein feingranulares Permission-Modell ermöglicht eine präzise Steuerung von Funktionszugriffen.
  • Die modulbezogene Struktur unterstützt die unabhängige Entwicklung und Erweiterung einzelner Fachbereiche.
  • Rollen vereinfachen die Administration, indem sie mehrere Berechtigungen bündeln.
  • Die Trennung von Rollen und Permissions verhindert eine zu starke Kopplung der fachlichen Berechtigungslogik an vordefinierte Benutzerrollen.
  • Neue Berechtigungen können ergänzt werden, ohne bestehende Rollen- oder Modulstrukturen grundlegend verändern zu müssen.

Konsequenzen:

  • Jedes Modul definiert seine benötigten Permissions.
  • Permissions folgen einer einheitlichen Namenskonvention.
  • Rollen werden durch Kombinationen bestehender Permissions definiert.
  • Die Autorisierung erfolgt anhand konkreter Permissions und nicht ausschließlich anhand von Rollen.
  • Backend-Endpunkte und fachliche Operationen müssen die erforderlichen Permissions prüfen.
  • Die Verwaltung und Zuordnung von Rollen und Permissions muss zentral nachvollziehbar sein.
  • Permissions gelten immer im Kontext einer Organisation und eines freigeschalteten Entitlements.

Regeln (verbindlich):

  • Namensschema: <modul>:<ressource>:<aktion> in Kleinbuchstaben, Aktionen aus read, write, delete, manage und bei Bedarf fachliche Aktionen (z. B. approve).
  • Jedes Modul deklariert seine Permissions zentral in einer Permission-Registry. Nicht deklarierte Permissions dürfen NICHT verwendet werden.
  • Jeder Endpunkt ist mit einer Permission-Anforderung annotiert (z. B. Decorator). Endpunkte ohne Annotation sind nur erlaubt, wenn sie explizit als öffentlich markiert sind.
  • Code prüft Permissions, NICHT Rollennamen. Rollen werden nirgends im Code hartcodiert abgefragt.
  • Eine Permission ist nur wirksam, wenn die Organisation das zugehörige Modul-Entitlement besitzt.
  • Rollen- und Permission-Änderungen werden im Audit-Log protokolliert.

ADR-007: REST-API mit OpenAPI und generiertem Angular-Client

Entscheidung:

Die Kommunikation zwischen Frontend und Backend erfolgt über REST-Schnittstellen. Die API wird mittels OpenAPI spezifiziert. Aus der OpenAPI-Spezifikation wird der Angular-Client automatisch generiert. Eingehende DTOs werden validiert und Fehler im Format RFC 9457 (Problem Details) zurückgegeben.

Begründung:

  • REST bietet einen etablierten und breit unterstützten Standard für die Kommunikation zwischen Frontend und Backend.
  • OpenAPI schafft einen verbindlichen und maschinenlesbaren API-Vertrag.
  • Die automatische Generierung des Angular-Clients reduziert manuellen Implementierungsaufwand und verhindert Inkonsistenzen zwischen Frontend und Backend.
  • DTO-Validierung stellt sicher, dass ungültige oder unvollständige Eingaben frühzeitig erkannt werden.
  • Ein standardisiertes Fehlerformat (RFC 9457) vereinfacht die Fehlerbehandlung im Frontend und die Auswertung durch Entwickler und KI-Agenten, ohne ein eigenes Format erfinden zu müssen.
  • Eine einheitliche Konvention für Pagination, Sortierung und Filter verhindert, dass jede Story eine eigene Variante einführt.

Konsequenzen:

  • Alle öffentlichen Backend-Schnittstellen müssen in der OpenAPI-Spezifikation dokumentiert werden.
  • Der Angular-Client wird aus der aktuellen API-Spezifikation generiert und nicht manuell gepflegt.
  • Änderungen an API-Verträgen müssen sowohl im Backend als auch in der generierten Client-Bibliothek berücksichtigt werden.
  • Eingehende Daten müssen serverseitig validiert werden.
  • Fehlerantworten folgen einer einheitlichen Struktur und enthalten geeignete Fehlercodes sowie nachvollziehbare Informationen.
  • Breaking Changes an APIs müssen bewusst versioniert bzw. koordiniert werden.

Regeln (verbindlich):

  • Fehlerantworten verwenden application/problem+json (RFC 9457) mit stabilem, maschinenlesbarem Fehlercode (code) und, bei Validierungsfehlern, Feldfehlern.
  • Jedes DTO wird per Validierung (z. B. class-validator) abgesichert. Unbekannte Felder werden abgelehnt (Whitelist).
  • Entities werden NICHT direkt als API-Antwort ausgeliefert, sondern über eigene Response-DTOs.
  • Listen-Endpunkte nutzen eine einheitliche Konvention für Pagination (page/pageSize oder Cursor), Sortierung und Filter. Die Konvention ist in einem Referenzmodul umgesetzt und wird kopiert.
  • Der Angular-Client wird in der CI neu generiert. Ein Unterschied zum eingecheckten Stand lässt die CI fehlschlagen.
  • Der generierte Client wird NICHT manuell editiert.
  • Nach außen sichtbare Fehlermeldungen enthalten KEINE internen Details (Stacktraces, SQL).

ADR-008: Datenbankkonventionen und Datenintegrität

Entscheidung:

Für Datenbankänderungen werden ausschließlich TypeORM-Migrationen verwendet. Die automatische Synchronisierung des Datenbankschemas über synchronize ist deaktiviert. Primärschlüssel werden als UUID (Version 7) definiert. Geldbeträge werden als numeric mit fest definierter Skalierung gespeichert und im Code mit einem Decimal-Typ verarbeitet. Datensätze werden grundsätzlich über Soft-Delete oder fachliche Stornierung behandelt, anstatt sie physisch zu löschen.

Begründung:

  • Explizite Migrationen gewährleisten nachvollziehbare und reproduzierbare Datenbankänderungen.
  • Die Deaktivierung von synchronize verhindert unkontrollierte Schemaänderungen zur Laufzeit.
  • UUIDs ermöglichen global eindeutige Identifikatoren und erleichtern die Integration verschiedener Module und Systeme. UUIDv7 ist zeitlich sortierbar und für Indizes deutlich günstiger als zufällige UUIDv4.
  • Geldbeträge dürfen aufgrund von Rundungsfehlern nicht mit binären Gleitkommazahlen verarbeitet werden. Sie müssen in der DB immer mit fest definierter Anzahl an Nachkommastellen gespeichert werden.
  • Eine einzige festgelegte Variante verhindert uneinheitlichen Code durch Agenten.
  • Soft-Delete und Stornierung erhalten die historische Nachvollziehbarkeit und unterstützen fachliche Audit-Anforderungen.
  • Eine klare Trennung zwischen Datum (date) und Zeitpunkt (timestamptz) verhindert Fehler an Monats- und Quartalsgrenzen.
  • Die Regeln schaffen eine einheitliche Grundlage für Datenhaltung und Datenintegrität.

Konsequenzen:

  • Jede Änderung am Datenbankschema muss durch eine versionierte TypeORM-Migration erfolgen.
  • Migrationen müssen in Entwicklungs-, Test- und Produktionsumgebungen reproduzierbar ausführbar sein.
  • Primär- und Fremdschlüssel werden grundsätzlich als UUID umgesetzt.
  • Geldbeträge müssen mit geeigneten Datentypen und einer eindeutigen Währungs- bzw. Einheitendefinition gespeichert werden.
  • Fachliche Löschvorgänge müssen zwischen Soft-Delete und Stornierung unterscheiden.
  • Physisches Löschen ist nur für ausdrücklich definierte technische oder datenschutzrechtliche Anwendungsfälle zulässig.
  • Abfragen müssen den Status gelöschter bzw. stornierter Datensätze korrekt berücksichtigen.
  • TypeORM liefert numeric standardmäßig als String. Ein zentraler Transformer wandelt in den Decimal-Typ und zurück.

Regeln (verbindlich):

  • synchronize ist in ALLEN Umgebungen false. Schemaänderungen erfolgen nur über Migrationen, die in der CI gegen eine leere DB laufen.
  • Primärschlüssel: UUIDv7, einheitlich über eine zentrale Hilfsfunktion erzeugt.
  • Geldbeträge: Spaltentyp numeric(19,4), im Code Decimal-Typ (z. B. decimal.js), NIE number/float. Ein zentraler Transformer ist Pflicht.
  • Zu jedem Geldbetrag wird die Währung (ISO 4217) mitgespeichert, auch wenn zunächst nur EUR genutzt wird.
  • Fachliche Datumswerte (z. B. Buchungsdatum, Valutadatum) sind date. Zeitpunkte sind timestamptz in UTC. Die Darstellung erfolgt in Europe/Vienna.
  • Jede mandantenbezogene Tabelle besitzt organization_id, created_at, updated_at, created_by sowie bei Soft-Delete deleted_at.
  • Fremdschlüssel erhalten einen Index.
  • Physisches Löschen ist nur über explizit benannte Services für Datenschutzlöschung oder technische Bereinigung zulässig.
  • Standardabfragen schließen soft-gelöschte Datensätze aus. Der Ausschluss ist zentral umgesetzt und wird NICHT in jeder Query neu geschrieben.
  • Migrationen sind nach dem Merge unveränderlich. Korrekturen erfolgen durch neue Migrationen.

ADR-009: Zentrales KI-Gateway

Entscheidung:

Die Integration von KI-Funktionalitäten erfolgt ausschließlich über ein zentrales KI-Gateway. Dieses abstrahiert die unterschiedlichen KI-Provider (zunächst lokales Ollama, später optional Cloud-Provider pro Organisation) und stellt eine einheitliche Schnittstelle bereit. Die Verarbeitung unterstützt asynchrone Queues, strukturierte Ausgaben, versionierte Prompts und ein zentrales Nutzungslogging. KI-Ergebnisse sind Vorschläge und werden nicht automatisch in fachliche Daten übernommen.

Begründung:

  • Eine zentrale Abstraktionsschicht verhindert eine direkte Abhängigkeit einzelner Module von bestimmten KI-Providern.
  • Der Austausch oder die Erweiterung von Providern wird dadurch deutlich vereinfacht.
  • Eine Queue ermöglicht die kontrollierte und asynchrone Verarbeitung zeitintensiver KI-Anfragen. Bei lokalen Modellen ist der Durchsatz der begrenzende Faktor.
  • Strukturierte Ausgaben erleichtern die zuverlässige Weiterverarbeitung von KI-Ergebnissen durch die Anwendung.
  • Prompt-Versionierung ermöglicht reproduzierbare Ergebnisse und eine nachvollziehbare Weiterentwicklung von KI-Funktionalitäten.
  • Nutzungslogs schaffen Transparenz über Kosten, Verbrauch und tatsächliche Nutzung.
  • Gesundheitsdaten und Daten von Minderjährigen unterliegen besonderen Datenschutzanforderungen und dürfen die eigene Infrastruktur nicht verlassen.
  • Sprachmodelle können sich irren. Bei Finanz- und Gesundheitsdaten muss ein Mensch bestätigen.

Konsequenzen:

  • Fachmodule greifen nicht direkt auf externe KI-Provider zu.
  • Provider-spezifische Implementierungen werden ausschließlich innerhalb des KI-Gateways gekapselt.
  • KI-Anfragen und -Antworten müssen einem definierten Datenmodell folgen.
  • Prompts werden versioniert und nachvollziehbar verwaltet.
  • Nutzungsdaten werden zentral erfasst und können für Monitoring, Kostenkontrolle und Abrechnung verwendet werden.
  • Asynchrone Anfragen müssen einen nachvollziehbaren Status und eine Möglichkeit zur Fehlerbehandlung besitzen.
  • Datenschutz und der Umgang mit personenbezogenen Daten müssen bei der Übermittlung an externe Provider berücksichtigt werden.
  • Die UI muss Wartezeiten, Fehler und Timeouts der KI sauber darstellen und darf nie von einer sofortigen Antwort ausgehen.

Regeln (verbindlich):

  • Fachmodule rufen KI ausschließlich über die Schnittstelle des KI-Gateways auf. Direkte HTTP-Aufrufe an Ollama oder Cloud-Provider außerhalb des Gateways sind verboten.
  • Jede KI-Anfrage trägt den Organisationskontext. Provider, Modell und eine eventuelle Cloud-Freigabe werden pro Organisation konfiguriert, Standard ist ausschließlich lokal.
  • Daten mit der Klassifizierung "Gesundheit" oder "Minderjährige" dürfen NIE an Cloud-Provider gesendet werden. Diese Regel ist im Gateway hart verankert und NICHT per Konfiguration abschaltbar.
  • Jede Aufgabe verwendet ein JSON-Schema für die Ausgabe. Antworten werden validiert, ungültige Antworten werden kontrolliert wiederholt oder als Fehler gemeldet.
  • KI-Ergebnisse werden als Vorschlag mit Status (open, accepted, rejected) gespeichert. Sie schreiben NIE direkt in fachliche Daten. Die Übernahme erfolgt durch den Benutzer oder durch eine explizit konfigurierte Regel.
  • Prompts liegen in einer Prompt-Registry mit Version. Das Nutzungslog speichert Prompt-Version, Modell, Dauer, Tokenzahl und Status.
  • Eingaben und Ausgaben im Nutzungslog werden nur nach Konfiguration und mit definierter Aufbewahrungsdauer gespeichert, personenbezogene Daten werden maskiert.
  • Jede KI-Funktion hat eine definierte Rückfallebene, die ohne KI funktioniert.

ADR-010: Verbindliche Teststrategie und CI-Pipeline

Entscheidung:

Die Qualitätssicherung erfolgt über eine verbindliche Teststrategie und automatisierte CI-Pipeline (Gitea Actions). Diese umfasst Linting, Unit-Tests, Integrationstests mit einer echten Datenbank sowie E2E-Smoke-Tests. Die E2E-Tests berücksichtigen insbesondere auch mobile Viewports. Eine Definition of Done legt die verbindlichen Qualitätskriterien fest.

Begründung:

  • Automatisierte Qualitätsprüfungen reduzieren das Risiko, Fehler in bestehende Funktionalitäten einzuführen.
  • Unit-Tests ermöglichen die isolierte Prüfung fachlicher Logik.
  • Integrationstests mit einer echten Datenbank decken Probleme auf, die durch Mocking allein nicht erkannt werden können (insbesondere RLS).
  • E2E-Smoke-Tests überprüfen die wichtigsten Anwendungsszenarien aus Benutzersicht.
  • Mobile Viewports stellen sicher, dass die Anwendung auch auf kleineren Geräten funktionsfähig bleibt.
  • Eine verbindliche Definition of Done schafft ein einheitliches Qualitätsverständnis für Entwickler und KI-Agenten.
  • Ohne automatische Prüfung ist autonom arbeitenden Agenten kein sicherer Integrationsprozess möglich.

Konsequenzen:

  • Alle Änderungen müssen die definierten Qualitätsprüfungen erfolgreich durchlaufen.
  • Linting und Unit-Tests werden automatisiert in der CI ausgeführt.
  • Integrationstests verwenden eine echte PostgreSQL-Datenbank.
  • E2E-Smoke-Tests prüfen die wichtigsten fachlichen Abläufe.
  • Mobile Viewports werden in die automatisierten Oberflächentests einbezogen.
  • Neue Funktionalitäten müssen entsprechend ihrer fachlichen und technischen Risiken getestet werden.
  • Die Definition of Done wird als verbindliche Grundlage für die Abnahme von Tickets verwendet.

Regeln (verbindlich):

  • Pipeline-Stufen: Lint (inkl. Modulgrenzen), Typprüfung, Unit-Tests, Integrationstests (echte PostgreSQL), OpenAPI-Client-Check, Isolationstest-Suite, Build, E2E-Smoke (mindestens ein Desktop- und ein Mobile-Viewport mit 360 px), Secret-Scan.
  • Ein Pull Request darf nur gemergt werden, wenn alle Stufen grün sind.
  • Neue oder geänderte Logik benötigt Tests. Fehlerbehebungen beginnen mit einem Test, der den Fehler reproduziert.
  • Integrationstests mocken die Datenbank NICHT.
  • Tests dürfen NICHT übersprungen oder deaktiviert werden (skip, xit), um die CI grün zu machen.
  • Definition of Done: Abnahmekriterien erfüllt, Tests vorhanden und grün, Lint grün, Mobile-Ansicht (360 px) geprüft, Texte über i18n, Permissions und Entitlements geprüft, Migration inklusive RLS (falls nötig), Audit-Log (falls fachlich relevant), Dokumentation/ADR aktualisiert (falls betroffen), Ticket-Log gepflegt.

ADR-011: Standardisierter Agenten-Workflow

Entscheidung:

Die softwaregestützte Entwicklung durch KI-Agenten folgt einem standardisierten Workflow. Jedes Ticket erhält einen eigenen Git-Branch. Änderungen werden über Pull Requests eingebracht und anhand einer einheitlichen PR-Vorlage dokumentiert. Kanboard dient als zentrale Plattform für die Steuerung des Entwicklungsprozesses. Verbindliche Review-Regeln definieren die Qualitätsanforderungen vor der Integration. Das Ticket-Template wird um die Abschnitte "Nicht im Scope" und "Leitplanken / Referenzen" ergänzt.

Begründung:

  • Eine einheitliche Vorgehensweise ermöglicht die kontrollierte Zusammenarbeit mehrerer KI-Agenten.
  • Separate Branches verhindern, dass parallele Arbeiten unmittelbar miteinander kollidieren.
  • Pull Requests schaffen einen nachvollziehbaren und überprüfbaren Integrationsprozess.
  • Kanboard stellt sicher, dass der Status und Fortschritt der einzelnen Arbeitsschritte zentral dokumentiert werden.
  • Verbindliche Review-Regeln reduzieren das Risiko, fehlerhafte oder unvollständige Implementierungen zu integrieren.
  • Der standardisierte Prozess ermöglicht eine weitgehende Automatisierung des Softwareentwicklungszyklus.
  • Ein expliziter Abschnitt "Nicht im Scope" verhindert, dass Agenten über die Aufgabe hinaus Änderungen vornehmen.

Konsequenzen:

  • Jedes Ticket erhält einen eigenen Entwicklungsbranch.
  • Änderungen werden grundsätzlich über Pull Requests integriert.
  • Pull Requests müssen die definierten Informationen und Prüfkriterien enthalten.
  • Der Kanboard-Statusfluss bildet den verbindlichen Fortschritt der Entwicklung ab.
  • Review- und Freigaberegeln müssen vor der Integration erfüllt sein.
  • KI-Agenten müssen den definierten Workflow einhalten und ihre Arbeitsergebnisse nachvollziehbar dokumentieren.
  • Der Prozess muss menschliche Eingriffe und Freigaben an den dafür vorgesehenen Stellen ermöglichen.
  • Zunächst erfolgt das Review ausschließlich durch den Product Owner. Später werden ein Code-Reviewer-Agent und ein Security-Reviewer-Agent vorgeschaltet, ohne den menschlichen Freigabeschritt zu ersetzen.

Regeln (verbindlich):

  • Branch-Name: feature/<ticket-id>-<kurzbeschreibung> (bei Fehlern fix/...). Es wird NICHT direkt auf dev oder main gepusht.
  • Ein Ticket entspricht einem Branch und einem Pull Request. Mehrere Tickets werden NICHT in einem PR vermischt.
  • Der Agent bearbeitet nur das, was im Ticket steht, und hält den Abschnitt "Nicht im Scope" ein. Auffälligkeiten außerhalb des Scopes werden als Notiz bzw. neues Ticket festgehalten, NICHT stillschweigend umgesetzt.
  • Der Agent pflegt Sub-Tasks (Häkchen) und den Abschnitt "Logs / Notizen". Ziel, Kontext, Analyse und Abnahmekriterien werden vom Agenten NICHT verändert.
  • Commit-Nachrichten folgen Conventional Commits und enthalten die Ticket-ID.
  • Die PR-Vorlage enthält: Ticket-Link, Zusammenfassung, Abweichungen vom Ticket, Teststatus, Checkliste der Definition of Done, Hinweise für das Review.
  • Ist ein Ticket unklar oder widersprüchlich, stoppt der Agent und vermerkt die offene Frage im Ticket, anstatt zu raten.
  • Der Agent ändert NICHT eigenmächtig ADRs, CI-Konfiguration, Berechtigungsmodell oder Migrationen bereits gemergter Stände. Solche Änderungen erfordern ein eigenes, ausdrücklich dafür vorgesehenes Ticket.
  • Der Merge nach dev erfolgt erst nach grüner CI und Freigabe.
  • Statusfluss in Kanboard: Backlog, Bereit, In Arbeit, In Review, Erledigt (Anpassung beim Aufsetzen des Boards möglich).

ADR-012: Mobile-First-Entwicklung und Accessibility

Entscheidung:

Die Benutzeroberfläche wird nach dem Mobile-First-Prinzip entwickelt. Der initiale Entwurf und die grundlegende Funktionalität müssen bereits ab einer Viewport-Breite von 360 px funktionieren. Touch-Ziele werden ausreichend groß dimensioniert. Tabellen werden auf mobilen Geräten in eine geeignete Kartenansicht überführt. Grundlegende Accessibility-Anforderungen sowie Internationalisierung (i18n) werden von Beginn an berücksichtigt. Die erste unterstützte Sprache ist Deutsch. Die Anwendung wird als Progressive Web App (PWA) bereitgestellt.

Begründung:

  • Mobile First stellt sicher, dass die Anwendung auch auf Smartphones sinnvoll nutzbar ist.
  • Eine frühe Berücksichtigung kleiner Viewports verhindert aufwendige nachträgliche Anpassungen.
  • Kartenansichten ermöglichen eine bessere Darstellung komplexer tabellarischer Informationen auf kleinen Bildschirmen.
  • Accessibility verbessert die Nutzbarkeit für Menschen mit unterschiedlichen Einschränkungen und unterstützt eine konsistente Bedienbarkeit.
  • Eine frühzeitige Integration von i18n verhindert eine spätere starke Kopplung der Anwendung an einzelne Sprachen.
  • Die anfängliche Beschränkung auf Deutsch reduziert den Implementierungsaufwand, ohne zukünftige Mehrsprachigkeit auszuschließen.
  • Eine PWA ermöglicht Installation, Kamerazugriff (z. B. Barcode-Scan und Essensfotos) und Push-Benachrichtigungen ohne native App.

Konsequenzen:

  • Das Layout wird zunächst für kleine Viewports entwickelt und anschließend für größere Bildschirmgrößen erweitert.
  • Die Mindestanforderung für die Darstellung liegt bei 360 px Viewport-Breite.
  • Interaktive Elemente müssen für Touch-Bedienung geeignet sein.
  • Tabellen benötigen eine mobile Darstellungsvariante in Form von Karten oder einer gleichwertigen Lösung.
  • Grundlegende Accessibility-Anforderungen werden bereits bei der Implementierung berücksichtigt.
  • Sämtliche benutzerseitig sichtbaren Texte müssen über das i18n-System verwaltet werden.
  • Deutsch wird zunächst als einzige Sprache ausgeliefert.
  • Neue Komponenten müssen die Mobile-First- und Accessibility-Vorgaben einhalten.
  • Offline-Betrieb ist nicht Teil des Umfangs (frühestens V2/V3), die Architektur schließt ihn aber nicht aus.

Regeln (verbindlich):

  • Stile werden mobile-first geschrieben (Basis für 360 px, Erweiterungen über min-width-Breakpoints). Keine horizontale Scrollleiste der Seite bei 360 px.
  • Touch-Ziele haben mindestens 44 x 44 px.
  • Datentabellen haben eine Kartenvariante für kleine Viewports. Eine gemeinsame Tabellen-Komponente wird wiederverwendet, es werden KEINE eigenen Tabellen pro Feature gebaut.
  • Barrierefreiheit: semantisches HTML, Tastaturbedienung, sichtbarer Fokus, Beschriftungen für Formularfelder, ausreichender Farbkontrast, Verwendung geprüfter Primitive (z. B. Angular Aria).
  • Es gibt KEINE hartcodierten Texte in Templates oder Komponenten. Alle Texte laufen über das i18n-System mit Schlüsseln.
  • Zahlen, Beträge und Datumsangaben werden über Locale-abhängige Formatierung ausgegeben (de-AT), NICHT per Stringverkettung.
  • Der Service Worker und das Web-App-Manifest werden zentral in der Shell gepflegt.

ADR-013: DSGVO-Basis und Datenschutzanforderungen

Entscheidung:

Die Anwendung berücksichtigt grundlegende Anforderungen der Datenschutz-Grundverordnung (DSGVO) von Beginn an. Dazu gehören insbesondere die Verwaltung von Einwilligungen (Consent), die Möglichkeit zum Datenexport, ein definiertes Löschkonzept sowie ein Audit-Log zur Nachvollziehbarkeit relevanter Vorgänge. Für Gesundheitsdaten und Daten von Minderjährigen gelten zusätzliche Schutzmaßnahmen.

Begründung:

  • Datenschutzanforderungen müssen bereits bei der Architektur und Datenmodellierung berücksichtigt werden.
  • Eine nachträgliche Implementierung datenschutzrechtlicher Anforderungen verursacht häufig erhebliche technische und organisatorische Aufwände.
  • Die Verwaltung von Einwilligungen ermöglicht eine nachvollziehbare Dokumentation entsprechender Entscheidungen.
  • Datenexport und Löschkonzepte unterstützen die Wahrnehmung von Betroffenenrechten.
  • Audit-Logs schaffen Transparenz über sicherheits- und geschäftsrelevante Vorgänge.
  • Die frühzeitige Berücksichtigung unterstützt das Prinzip Privacy by Design.
  • Gesundheitsdaten zählen zu den besonderen Kategorien personenbezogener Daten (Art. 9 DSGVO). Für Kinder (in Österreich unter 14 Jahren) ist die Einwilligung der Erziehungsberechtigten erforderlich.

Konsequenzen:

  • Einwilligungen müssen nachvollziehbar und mit ihrem jeweiligen Gültigkeitskontext gespeichert werden.
  • Es muss eine Möglichkeit zum Export personenbezogener Daten vorgesehen werden.
  • Ein Löschkonzept definiert, welche Daten wann und auf welche Weise gelöscht oder anonymisiert werden.
  • Gesetzliche Aufbewahrungs- und Dokumentationspflichten müssen bei Löschvorgängen berücksichtigt werden.
  • Relevante Änderungen und sicherheitskritische Vorgänge werden in einem Audit-Log dokumentiert.
  • Audit-Logs müssen vor unberechtigter Veränderung und Einsichtnahme geschützt werden.
  • Die Umsetzung muss regelmäßig hinsichtlich ihrer datenschutzrechtlichen Anforderungen überprüft werden.
  • Kinderkonten sind an eine Eltern-Organisation (Familie) gebunden und werden von den Erziehungsberechtigten verwaltet.
  • Für den Betrieb als SaaS sind Auftragsverarbeitungsverträge, Verarbeitungsverzeichnis und Datenschutzerklärung außerhalb des Codes zu erstellen. Dies ist nicht Teil der Agenten-Tickets, wird aber in der Roadmap vermerkt.

Regeln (verbindlich):

  • Personenbezogene Felder werden im Datenmodell als solche gekennzeichnet, damit Export und Löschung sie auffinden können.
  • Jedes Modul, das personenbezogene Daten speichert, stellt einen Export- und einen Lösch-/Anonymisierungs-Handler für die Plattform bereit.
  • Das Audit-Log ist append-only (kein Update, kein Delete über die Anwendung) und nur für berechtigte Rollen lesbar.
  • Das Audit-Log protokolliert Anmeldungen, Rechteänderungen, Organisations- und Entitlement-Änderungen, AccessGrant-Änderungen und fachlich sensible Änderungen. Es enthält keine Passwörter, Tokens und keine überflüssigen Inhalte.
  • Einwilligungen werden mit Zweck, Version des Textes, Zeitpunkt und Quelle gespeichert.
  • Daten der Kategorien "Gesundheit" und "Minderjährige" werden im Datenmodell klassifiziert (Grundlage für ADR-009).
  • Beim Löschen einer Organisation oder eines Benutzers wird zuerst geprüft, welche Aufbewahrungsfristen gelten (z. B. Finanzdaten). Löschung und Anonymisierung folgen dem Löschkonzept.

ADR-014: PostgreSQL-basierte Queue für Hintergrundjobs

Entscheidung:

Hintergrundjobs werden über eine PostgreSQL-basierte Queue abgewickelt. Als Implementierung wird pg-boss eingesetzt. Auf den Einsatz einer zusätzlichen Redis-Infrastruktur wird zunächst verzichtet.

Begründung:

  • PostgreSQL ist bereits Bestandteil der Anwendungsinfrastruktur und kann somit auch für die Job-Verarbeitung genutzt werden.
  • Eine zusätzliche Redis-Instanz würde den Infrastruktur- und Wartungsaufwand erhöhen.
  • Eine PostgreSQL-basierte Queue ermöglicht die persistente Speicherung und Verarbeitung von Hintergrundjobs.
  • Die Verwendung einer gemeinsamen Datenbankinfrastruktur vereinfacht Deployment, Monitoring und Betrieb.
  • Die Lösung ist insbesondere für einen modularen Monolithen mit überschaubarem Infrastrukturbedarf geeignet.
  • Jobs laufen außerhalb eines Requests und müssen den Organisationskontext daher selbst herstellen, sonst würden sie an der Mandantenisolation vorbeiarbeiten.

Konsequenzen:

  • Hintergrundjobs werden zentral über eine PostgreSQL-basierte Queue verwaltet.
  • Die Queue-Implementierung wird hinter einer geeigneten Abstraktion gekapselt, damit ein späterer Technologiewechsel möglich bleibt.
  • Job-Handler müssen Fehler und Wiederholungsversuche kontrolliert behandeln.
  • Die Verarbeitung muss sicherstellen, dass Jobs nicht unbeabsichtigt mehrfach fachliche Auswirkungen erzeugen (Idempotenz).
  • Monitoring und Logging müssen den Status und die Ausführung von Hintergrundjobs nachvollziehbar machen.
  • Die zusätzliche Datenbanklast durch Queue-Verarbeitung muss berücksichtigt werden.
  • Ein Wechsel auf eine dedizierte Queue-Infrastruktur bleibt bei steigenden Anforderungen eine mögliche Option.

Regeln (verbindlich):

  • Jeder Job trägt die organizationId und setzt den Organisationskontext (inklusive RLS, siehe ADR-005), bevor er fachlich arbeitet. Jobs ohne Organisationsbezug sind explizit als systemweit markiert.
  • Job-Payloads enthalten nur IDs und technische Parameter, KEINE personenbezogenen Daten oder Beträge.
  • Jeder Job-Handler ist idempotent und besitzt definierte Wiederholungs- und Timeout-Regeln sowie eine Fehlerbehandlung (Dead-Letter).
  • Die Queue-Tabellen liegen in einem eigenen Datenbankschema und sind von der Organisations-RLS ausgenommen, der Zugriff erfolgt nur über die Queue-Abstraktion.
  • Module verwenden die Queue ausschließlich über die Abstraktion im core, nicht direkt über pg-boss.
  • Geplante Jobs (z. B. Erinnerungen) werden zentral registriert und sind in Logs und im Plattform-Admin einsehbar.

ADR-015: Frontend-Konventionen (Angular 22)

Entscheidung:

Das Frontend wird mit Angular 22 nach dem aktuellen Signal-First-Ansatz entwickelt: Standalone-Komponenten, Signals, Signal Forms, Resource API und OnPush als Standard der Change Detection. Ältere Muster (NgModules, Zone.js-abhängige Idiome, ältere Template-Syntax) werden nicht verwendet.

Begründung:

  • Angular 22 hat zentrale Signal-APIs (Signal Forms, Resource API) stabilisiert und OnPush zum Standard gemacht. Sie sind der empfohlene Weg.
  • Sprachmodelle kennen Angular 22 nur eingeschränkt und neigen zu veralteten Mustern. Eine explizite Vorgabe samt Referenzbeispielen verhindert uneinheitlichen Code.
  • Ein einheitlicher Stil reduziert den Review-Aufwand.

Konsequenzen:

  • Es existiert ein Referenzmodul im Repo, das die empfohlenen Muster zeigt (Liste, Detail, Formular, Fehlerbehandlung, Ladezustände).
  • ESLint-Regeln unterbinden veraltete Muster nach Möglichkeit automatisch.
  • Die offiziellen Angular-Agent-Skills und die Dokumentation werden in die Agenten-Konfiguration eingebunden.
  • Bei einem Angular-Update wird dieses ADR überprüft.

Regeln (verbindlich):

  • Nur Standalone-Komponenten, KEINE NgModule.
  • Zustand und Ableitungen über Signals (signal, computed, linkedSignal, effect sparsam). Formulare über Signal Forms. Datenabruf über die Resource API bzw. die generierten API-Services.
  • Neue Control-Flow-Syntax (@if, @for, @switch) statt *ngIf/*ngFor.
  • Komponenten verwenden OnPush (Standard), KEINE Abhängigkeit von Zone.js-Eigenheiten.
  • Abhängigkeiten werden per inject() bezogen.
  • Komponenten sind klein und aufgabenbezogen. Geschäftslogik liegt in Services bzw. im Backend, NICHT in Templates.
  • Feature-Code importiert nur über die öffentliche API (index.ts) einer Bibliothek.
  • Jeder Datenabruf behandelt Lade-, Leer- und Fehlerzustand.
  • Keine direkten HttpClient-Aufrufe in Komponenten, es wird der generierte Client verwendet.
  • Es wird eine einheitliche Komponentenbasis (Design-System in shared/ui) verwendet. Eine externe UI-Bibliothek wird nur nach separatem ADR eingeführt.

ADR-016: Kommunikation zwischen Modulen

Entscheidung:

Module kommunizieren ausschließlich über öffentlich definierte Service-Interfaces und Domain Events. Direkter Zugriff auf Repositories, Entities oder Tabellen eines anderen Moduls ist nicht zulässig.

Begründung:

  • ADR-001 fordert definierte Schnittstellen, legt aber nicht fest, wie diese aussehen.
  • Lose Kopplung hält die Option offen, ein Modul später auszugliedern.
  • Klare Schnittstellen sind für Agenten leichter zu befolgen als implizite Konventionen.

Konsequenzen:

  • Jedes Modul besitzt eine öffentliche API (Interfaces, DTOs, Events) in einem klar bezeichneten Bereich.
  • Synchrone Abfragen laufen über Service-Interfaces, Benachrichtigungen über Domain Events.
  • Fremdschlüssel zwischen Tabellen verschiedener Module sind nur auf Tabellen des core erlaubt (z. B. organization, user) oder werden als lose ID ohne Datenbank-Constraint geführt.
  • Gemeinsam genutzte Konzepte mit mehreren Modulen (z. B. Finanz-Kern für Unternehmens- und Kinderfinanzen) werden bewusst in eine gemeinsame Bibliothek ausgelagert und nicht kopiert.

Regeln (verbindlich):

  • Kein Import von Entities, Repositories oder internen Services eines anderen Fachmoduls.
  • Der Zugriff auf core erfolgt über dessen öffentliche Schnittstellen.
  • Domain Events sind versioniert, tragen organizationId und enthalten KEINE sensiblen Daten über das Notwendige hinaus.
  • Event-Handler sind idempotent und laufen im Organisationskontext (ADR-005, ADR-014).
  • Neue modulübergreifende Abhängigkeiten werden im Ticket begründet und im Review ausdrücklich bestätigt.

ADR-017: Logging und Beobachtbarkeit

Entscheidung:

Die Anwendung schreibt strukturierte Logs (JSON) mit einer Correlation-ID pro Request. Logs, Metriken und Fehler sind so gestaltet, dass sie Betrieb und Fehlersuche unterstützen, ohne personenbezogene oder finanzielle Inhalte offenzulegen.

Begründung:

  • Strukturierte Logs sind maschinell auswertbar und für Menschen und Agenten bei der Fehlersuche nützlich.
  • Eine Correlation-ID verbindet Frontend-Anfrage, Backend, Queue-Jobs und KI-Aufrufe.
  • Logs mit sensiblen Daten sind ein häufiger, vermeidbarer Datenschutzverstoß.

Konsequenzen:

  • Es gibt einen zentralen Logger mit festgelegten Feldern (Zeit, Level, Correlation-ID, organizationId, userId, Modul).
  • Health- und Readiness-Endpunkte sind vorhanden.
  • Ein Metrik- und Alarmierungskonzept wird beim Betriebs-ADR (ADR-019) konkretisiert.

Regeln (verbindlich):

  • Es wird ausschließlich der zentrale Logger verwendet, KEIN console.log im Produktivcode.
  • Pro Request wird eine Correlation-ID erzeugt bzw. übernommen und an Jobs und KI-Aufrufe weitergereicht.
  • Logs enthalten KEINE Passwörter, Tokens, Beträge, Gesundheitsdaten, Dokumentinhalte oder KI-Prompts im Klartext.
  • Fehler werden mit Correlation-ID geloggt, die dem Benutzer im Fehlerfall angezeigt werden kann.

ADR-018: Secrets und Konfiguration

Entscheidung:

Konfiguration erfolgt über Umgebungsvariablen und wird beim Start validiert. Secrets werden nie im Repository gespeichert. Die CI enthält einen Secret-Scan.

Begründung:

  • Autonom arbeitende Agenten haben Schreibzugriff auf das Repository und Zugriff auf Entwicklungsumgebungen. Das Risiko, dass Secrets versehentlich eingecheckt oder ausgegeben werden, steigt dadurch.
  • Eine validierte Konfiguration verhindert Fehlstarts und unklare Fehler.

Konsequenzen:

  • Es gibt eine dokumentierte .env.example ohne echte Werte.
  • Agenten arbeiten ausschließlich mit Entwicklungs-Zugangsdaten mit minimalen Rechten, nie mit Produktionszugängen.
  • Rotation und Verwaltung von Produktions-Secrets werden im Betriebs-ADR (ADR-019) festgelegt.

Regeln (verbindlich):

  • KEINE Secrets, Schlüssel oder Passwörter im Repository, in Tickets, Logs oder Testdaten.
  • Die Konfiguration wird beim Start gegen ein Schema validiert. Die Anwendung startet nicht mit fehlender oder ungültiger Konfiguration.
  • Neue Konfigurationswerte werden in .env.example und in der Konfigurationsdokumentation ergänzt.
  • Agenten haben KEINEN Zugriff auf Produktionssysteme, Produktionsdatenbanken oder Produktions-Secrets.
  • Der Secret-Scan ist Pflichtbestandteil der CI (ADR-010).

ADR-019: Betrieb, Backups und Umgebungen

Status: Vorgeschlagen (wird vor dem ersten produktiven Einsatz konkretisiert)

Entscheidung:

Die Anwendung wird auf eigener Infrastruktur per Docker betrieben. Es gibt getrennte Umgebungen für Entwicklung, Test und Produktion. Datenbank und Dateiablage werden regelmäßig gesichert und die Wiederherstellung wird getestet.

Begründung:

  • Mit Mandantendaten im SaaS-Betrieb sind Datenverlust und Ausfälle geschäftskritisch.
  • Ein Backup ohne getesteten Restore bietet keine verlässliche Sicherheit.
  • Die Entwicklungs-, Agenten- und KI-Last teilt sich zunächst Ressourcen auf demselben Server. Eine klare Trennung der Umgebungen verhindert gegenseitige Beeinträchtigung.

Konsequenzen:

  • Eine Container-Konfiguration (Docker Compose) bildet alle Dienste ab (PostgreSQL, Keycloak, Dateispeicher, Anwendung, Mailserver für Entwicklung).
  • Backup-Strategie für PostgreSQL (inklusive Point-in-Time-Recovery) und Dateiablage mit definierter Aufbewahrung.
  • Regelmäßige Restore-Tests werden dokumentiert.
  • Ressourcenplanung für den gemeinsamen Server (Ollama, CI, Agenten, Datenbank).
  • Die spätere Trennung von Kunden über zusätzliche Container-Sets bleibt möglich (gemeinsame DB ist der Startpunkt).

Regeln (verbindlich):

  • Umgebungen (dev, test, prod) sind strikt getrennt, mit eigenen Zugangsdaten.
  • Produktionsdaten werden NICHT in Entwicklungs- oder Testumgebungen kopiert, außer anonymisiert.
  • Migrationen werden in einer Testumgebung geprobt, bevor sie in Produktion laufen.
  • Backups sind verschlüsselt und werden regelmäßig durch einen Restore-Test geprüft.

ADR-020: Aufbewahrung und Unveränderbarkeit von Finanzdaten (Platzhalter)

Status: Vorgemerkt (wird vor Phase 2 ausgearbeitet)

Entscheidung:

Offen. Zu klären ist, wie Buchungen nach Abschluss geschützt werden, wie Stornos und Korrekturen abgebildet werden und welche Aufbewahrungs- und Nachvollziehbarkeitsanforderungen für das Finanzmodul gelten.

Begründung:

  • Das Finanztool ist ein Controlling- und Planungswerkzeug, soll aber die Arbeit von Buchhalter und Steuerberater unterstützen. Nachvollziehbarkeit und unveränderte Vergangenheitsdaten sind dafür sehr wertvoll.
  • Die Entscheidung beeinflusst das Datenmodell und sollte daher vor der Implementierung feststehen.

Konsequenzen:

  • Voraussichtlich Themen: Sperre abgeschlossener Perioden, Storno statt Änderung, Änderungshistorie, Aufbewahrungsfristen nach österreichischem Recht (mit Steuerberater abzustimmen), Exportformate.

Regeln (verbindlich):

  • Bis zur Ausarbeitung gelten die allgemeinen Regeln aus ADR-008 (Storno statt Löschen) und ADR-013 (Audit-Log).