breadcrumb-the-shire/docs/architektur.md

Architektur-Kompass

Letzte Aktualisierung: 2026-02-23

Kurze, verbindliche Architekturübersicht für den aktuellen Stand.

Begriffe (kurz)

• Tenant: Mandant, isolierter Daten- und Berechtigungsraum.
• Department: optionale organisatorische Untereinheit innerhalb eines Tenants.
• Role: Bündel von Berechtigungen.
• Permission: einzelne Berechtigung wie users.view.
• Policy: zentrale Autorisierungsregel für eine konkrete Fähigkeit.
• Ability: technischer Name einer Policy-Regel, z. B. admin.users.edit.submit.
• AuthorizationDecision: Ergebnis einer Policy (allow/deny, HTTP-Status, Fehlercode, Attribute).
• Tenant-Scope: Regel, ob ein User eine Ressource im Ziel-Tenant sehen oder ändern darf.
• Request: einzelner HTTP-Aufruf.
• Action: Datei unter pages/**, verarbeitet den Request.
• Service: Fachlogik unter lib/Service/**.
• Repository: SQL- und Mapping-Schicht unter lib/Repository/**.
• UUID-first: externe API gibt nur UUIDs aus, keine internen IDs.
• Contract-Test: Test für Architektur- und Schnittstellenregeln.

Zielbild (Stand heute)

• Server-gerenderte App plus REST-API unter /api/v1.
• Strikte Multi-Tenant-Isolation.
• Zentrale Autorisierung über AuthorizationService und Policies.
• API-Verträge sind UUID-first.

Request-Flow (verbindlich)

1. web/index.php lädt Bootstrap, Routing und Konfiguration.
2. Firewall, Session, Locale und Access-Control laufen.
3. Action unter pages/** nimmt Request an.
4. Action delegiert Fachlogik an Services.
5. Services nutzen Repositories für Datenzugriff.
6. Response wird als HTML, JSON oder Datei ausgegeben.

Schichtregeln (MUSS)

• pages/**: Input, Auth/AuthZ, Service-Aufruf, Response. Keine duplizierte Business-Logik.
• lib/Service/**: Fachlogik und Orchestrierung. Keine Superglobals, keine Header/Redirect-Ausgabe.
• lib/Repository/**: SQL, Filter, Paging, Mapping. Keine HTTP-, Session- oder Policy-Logik.
• templates/**: nur Rendering.

Sicherheits- und API-Regeln (MUSS)

• Autorisierung nur zentral über Policies.
• Tenant-Scope nicht lokal nachbauen.
• Scope-Denials pro Endpunkt-Semantik als 403 oder 404.
• API-Fehler einheitlich: error, optional errors.
• OpenAPI wird bei API-Änderungen im selben Merge aktualisiert.

Merge-Mindestchecks

• docker compose exec php vendor/bin/phpunit
• docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress