breadcrumb-the-shire/docs/03-architektur-request-flow.md

Architektur und Request-Flow

Letzte Aktualisierung: 2026-03-03

Ziel

Verstehen, wo Änderungen hingehören und wo nicht.

Request-Flow

1. web/index.php lädt Bootstrap, registriert den AppContainer und setzt globale Service-Auflösung.
2. RequestContext initialisiert request_id und Basis-Metadaten; X-Request-Id wird gesetzt.
3. Guard/Sicherheitslayer laufen.
4. Action in pages/** nimmt Input an.
5. Action delegiert an Service.
6. Service nutzt Repository für Datenzugriff.
7. Response wird als HTML/JSON ausgegeben.

API-Ergänzung:

1. ApiBootstrap::init() startet API-Audit (ApiAuditService) und API-System-Audit (ApiSystemAuditReporter).
2. ApiResponse::send() finalisiert beide Reporter (inkl. request_id-Korrelation).
3. System-Protokolle schreiben nur selektive api.request-Events (kein Voll-Request-Logging).

Schichtregeln

• pages/**: Input, Auth/AuthZ, Service-Aufruf, Response.
• lib/Service/**: Business-Regeln und Orchestrierung.
• lib/Repository/**: SQL, Filter, Mapping.
• templates/**: Rendering ohne Business-Logik.
• Request-Daten in Actions nur über requestInput() (keine Input-Superglobals).
• Validierungsfehler zentral über FormErrors; API-Fehler über ApiResponse::validationFromFormErrors(...).
• Template-AuthZ konsumiert nur vorbereitete $viewAuth-Daten (kein can('...') im Template).
• Service-Auflösung in Actions/Helpern über app(Foo::class).
• Fachliche Audit-Events laufen zentral über SystemAuditService.
• Persistierte Status/Outcome-Werte laufen über die zentrale Taxonomie-Schicht lib/Domain/Taxonomy/* (Enums + DB-Checks).
• pages/**/data().php sind GET-only (gridRequireGetRequest()) und normalisieren limit/offset/order/dir über Grid-Helper.

Einfaches ASCII-Beispiel

Beispiel: GET /admin/users/data

Browser
  -> web/index.php (Bootstrap + AppContainer)
  -> pages/admin/users/data().php (Action)
      -> Guard + AuthorizationService (Auth/AuthZ)
      -> UserAccountService (Fachlogik)
          -> UserListQueryRepository (SQL + Filter + Paging)
              -> DB
      <- { data, total } JSON

Factory/Gateway im selben Bild:

AppContainer
  -> UserServicesFactory
      -> createUserAccountService() -> UserAccountService

Guard::requireAbilityOrForbidden(ops....)
  -> app(AuthorizationService::class)
      -> AccessPolicyFactory -> *AuthorizationPolicy
          -> PermissionGateway -> PermissionService -> PermissionRepository -> DB

Front Controller (web/index.php)
  -> app(UiAccessService::class)
      -> UiCapabilityMap::LAYOUT -> $viewAuth['layout']

Action
  -> app(UiAccessService::class)
      -> UiCapabilityMap::* -> $viewAuth['page']
          -> templates/** (nur Darstellung)

Absolute No-Go's

• SQL in View-Dateien
• Business-Logik in Actions
• Tenant-Scope als UI-Only-Check

Vertiefung

• Vollständiger Kompass: /docs/architektur.md
• Regeln für lib/**: /docs/lib-standards.md
• RBAC-Rechte erweitern: /docs/rbac-permissions-playbook.md