# 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`

```text
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:

```text
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`