Architektur: Zonen und Frontend#

Stand: 2026-09-30 · Beschreibt den Ist-Stand des Codes (Phase 2 abgeschlossen; Seiten für Mandanten und Demo-Pass aus Phase 4 in Abschnitt 8; gemeinsame Bausteine, Content Security Policy und cachebare Startseite in Abschnitt 9–11), nicht die Zielarchitektur. Kennzeichnung: [B] belegt (offizielle Quelle oder Messung), [A] Annahme, [E] Einschätzung.

Fachbegriffe sind in jedem Abschnitt beim ersten Vorkommen mit dem Glossar verlinkt (Erklärung und Entsprechung außerhalb von AWS).

Diese Seite ergänzt die Architektur um die Oberfläche: wie das Portal in mehrere Next.js-Apps zerfällt, wie der Browser schreibt, wie das Laufzeit-Widget „Glocke" eingebunden ist und was die Component Library liefert. Warum Multi-Zones statt Module Federation, steht in Next.js-Betrieb.

1. Zonen im Überblick#

Das Portal besteht aus der Shell und weiteren Zonen: je eine eigene Next.js-App mit eigenem basePath, eigener Lambda und eigenem Pfadbereich unter derselben Domain. Welche Zonen es gibt, steht an genau einer Stelle, der Registry infra/cdk/lib/zones.ts; App-Stack und Edge-Stack lesen sie beide.

Ein Wechsel zwischen Zonen ist ein voller Seitenwechsel (gewöhnlicher Link, kein clientseitiges Routing): Jede Zone hat ihr eigenes JavaScript-Bundle, und nur innerhalb einer Zone navigiert Next.js ohne Neuladen [E].

2. Aufbau einer Zone#

Eine Zone hinzuzufügen heißt: eine App unter apps/ mit basePath und output: "standalone" und ein Eintrag in zones.ts. Den Rest leiten die Stacks aus der Registry ab:

Statische Dateien kommen für Shell und Zonen aus dem S3-Bucket des Edge-Stacks. Anfangs lieferten die Zonen sie selbst aus; der erste Live-Test brach dann mit ReservedFunctionConcurrentInvocationLimitExceeded ab: ein erster Seitenaufruf lädt viele Chunks gleichzeitig, mehr als eine Reserved Concurrency von 2 zulässt [B: Live-Test 30.09.2026]. Seither laufen nur Seiten und Route Handler über die Lambda; die Next.js-Funktionen (Shell, Zonen) haben eine Reserved Concurrency von 5 (CDK-Kontext webReservedConcurrency), die Services weiterhin 2.

3. Anmeldung in den Zonen#

Die Anmeldung bleibt in der Shell; Zonen haben keinen eigenen OIDC-Ablauf. Das gemeinsame Paket @kundenportal/web-auth gibt jeder Zone dieselben Werkzeuge:

Ohne Sitzung leitet eine Zone zur Shell-Anmeldung weiter und kommt danach über returnTo zurück. Der Browser hält weiterhin nur Cookies, nie Tokens (BFF).

4. Schreibweg aus dem Browser#

Problem: CloudFront signiert Anfragen an die Function URLs per OAC mit SigV4. Für Anfragen mit Body (POST, PUT, PATCH) signiert CloudFront den Inhalt nicht selbst; der Absender muss den SHA-256 des Bodys im Header x-amz-content-sha256 mitschicken [B: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-lambda.html]. Ein gewöhnliches HTML-Formular kann das nicht.

Lösung: Alle schreibenden Aufrufe aus dem Browser laufen über sendJson(method, url, body) aus @kundenportal/web-auth/browser. Die Funktion serialisiert den Body, berechnet den Payload-Hash mit WebCrypto und sendet beides per fetch (nur gleiche Herkunft, mit Cookie).

• Live belegt [B]: POST an die Shell ohne Payload-Hash → 403 von CloudFront; mit Payload-Hash → die Anfrage erreicht die App.
• Function URLs bleiben AWS_IAM mit OAC. Die Alternativen wären eine öffentliche Function URL (Schutz nur noch über ein Geheimnis im Header, das dann im CloudFront-Template stünde) — beides verworfen [E].
• Folge: Formulare ohne JavaScript werden nicht unterstützt [E]. Das betrifft nur schreibende Aktionen; Seiten und Links funktionieren auch ohne JavaScript.

CSRF-Schutz in zwei Schichten:

1. Das Sitzungs-Cookie ist SameSite=Lax; fremde Seiten können damit keine POST-Anfragen mit Sitzung auslösen.
2. Jeder Route Handler, der schreibt, prüft den Origin-Header: nur die Portal-Domain, sonst 403; danach die Sitzung, sonst 401 (guardWrite in der Shell). Fehlt Origin, gilt die Anfrage als fremd — fetch sendet ihn bei allen Nicht-GET-Anfragen.

Schreibende Route Handler der Shell (Stand 30.09.2026):

Das Verhalten der Shell in CloudFront erlaubt dafür jetzt alle HTTP-Methoden (Phase 1: nur GET, HEAD, OPTIONS).

5. Laufzeit-Widget „Glocke"#

<kp-bell> (packages/widget-notifications) zeigt die Zahl der ungelesenen Nachrichten und verlinkt aufs Postfach. Es ist die zweite Integrationsart neben Multi-Zones: eine Laufzeit-Integration im Browser, die jede Zone unabhängig von ihrem eigenen Stack einbinden kann.

• Technik: ein Custom Element mit Shadow DOM, ohne Framework, gebaut mit Vite; 2,3 kB. Farben kommen über die Design-Tokens der Component Library (--kp-accent), mit Ersatzwerten.
• Einbinden: <script type="module" src="/widgets/bell.js"> und <kp-bell>; Attribute label, href (Standard /postfach), src (Standard /postfach/anzahl), interval (Sekunden, Standard 30).
• Auslieferung: Der Edge-Stack legt bell.js in den Asset-Bucket unter /widgets/; ein eigenes Verhalten /widgets/* liefert es gecacht aus. Weil der Dateiname gleich bleibt, invalidiert jeder Deploy /widgets/*.
• Daten: GET /postfach/anzahl der Shell mit dem Session-Cookie (gleiche Herkunft, kein Token im Browser). Ohne Sitzung antwortet die Route mit 401, das Widget bleibt dann still.

6. Component Library und Storybook#

packages/ui ist die gemeinsame Component Library aller Zonen; die Shell baut bereits vollständig darauf auf.

Der Workflow Pages veröffentlicht Storybook zusammen mit diesen Berichten auf GitHub Pages: https://janpfeil.github.io/kundenportal-demo/storybook/ — kostenlos und ohne S3 oder CloudFront (Kostenfreier Betrieb §3).

7. Messwerte#

Weitere Messwerte, auch der Deploy mit allen Services, stehen in Architektur §9.

8. Seiten für Mandanten und Demo-Pass (Phase 4)#

Die Architektur dahinter steht in Architektur: Mandanten und Demo-Pass.

Die Navigation der Shell hat dafür den Eintrag „Demo-Pass". Die beiden öffentlichen Route Handler brauchen keine Sitzung; sie laufen wie alle schreibenden Aufrufe über sendJson mit Payload-Hash (Abschnitt 4). Die Zahlen auf /pass/einloesen (Laufzeit, Kontingente, höchste Upload-Größe) holt der Browser von GET /api/tenancy/offer: gleiche Herkunft, ohne Token, ohne Umweg über die Shell-Lambda. Solange die Antwort fehlt, steht „Wird geladen …“ da, bei einem Fehler „nicht abrufbar“; das Formular bleibt dann nutzbar. Meldet die API redemptionOpen: false (Kill-Switch zu oder alle Plätze belegt), erscheint statt des Formulars der Hinweis „Einlösen ist gerade pausiert“.

Auf /cockpit/paesse sieht der Inhaber die Einstellungen: Einlösen offen oder gesperrt (mit Zeitpunkt und Grund, z. B. vom Budget-Alarm), Schaltfläche zum Sperren bzw. Wiederöffnen, die Zahl der aktiven Pass-Mandanten und die Höchstzahl 1–4 mit Begründung: Jeder Mandant hat eine Tabelle mit 5/5 Kapazitätseinheiten, frei sind 25/25 je Konto, die Basis belegt 5/5 (Mandanten §6). Ein erschöpftes Upload-Kontingent (429 vom Documents-Service) meldet das Upload-Formular mit eigenem Text.

9. Gemeinsame Bausteine der Zonen#

Was jede Zone gleich braucht, liegt in den Paketen; in der Zone bleiben nur basePath, Texte und Seiten.

10. Content Security Policy#

Shell und Zonen senden eine Content Security Policy (CSP). Gesetzt wird sie im proxy jeder App (src/proxy.ts, ab Next.js 16 der Nachfolger von middleware.ts) über createCspProxy aus @kundenportal/web-auth/csp.

Zwei Arten von Seiten:

• Seiten, die je Anfrage entstehen (alle Zonen, Konto, Postfach, Pass), bekommen je Antwort eine neue Nonce (128 bit). Der Proxy setzt die Policy auch in den Request-Header; Next.js liest die Nonce dort und hängt sie an seine Skripte.
• Vorgerenderte Seiten (/, /pass/einloesen, die 404-Seite) entstehen beim Build und können keine Nonce tragen. Ihr HTML ist je Build fest; der Proxy liest die Datei aus .next/server/app einmal je Lambda-Instanz und erlaubt genau ihre Inline-Skripte per SHA-256-Hash. Die Hashes der 404-Seite stehen in jeder Policy der Shell, weil jeder Pfad mit ihr antworten kann.

'strict-dynamic' ist nicht gesetzt: Alle Skripte kommen ohnehin von der eigenen Domain, und ohne 'strict-dynamic' funktionieren Nonce und Hash gleich. In next dev kommt 'unsafe-eval' hinzu (Fehleranzeige von React).

Lokal belegt [B: Produktionsbuild, headless Chromium, 30.09.2026]: keine Verletzung und vollständige Hydration auf Startseite (deutsch, englisch per Cookie und per Browsersprache), Einlöseseite (Angebot geladen, ALTCHA im Worker gelöst; zweiter Lauf mit pausiertem Einlösen), Konto, Postfach, Verträge mit Upload bis zum PUT an eine S3-Adresse, Verbrauch, Cockpit-Einstellungen (sperren, öffnen, Höchstzahl ändern) und 404-Seite. Gegenprobe: ein eingeschleustes Inline-Skript und ein fetch an eine fremde Domain werden blockiert.

11. Cachebare Startseite#

Bis 30.09.2026 las das gemeinsame Layout der Shell Cookies (Sitzung für die Navigation, Sprache); damit war jede Shell-Seite dynamisch und / kam mit private, no-store. Jetzt hat die Shell zwei Root-Layouts (Route Groups):

Die 404-Seite liefert app/global-not-found.tsx (zweisprachig), weil es kein gemeinsames Layout mehr gibt. Ein Wechsel zwischen den Gruppen ist ein voller Seitenwechsel, wie zwischen Zonen.

Wie die vorgerenderten Seiten den Besucher erkennen:

• Sprache: im Browser aus dem Cookie kp_locale (Sprachwechsel), sonst aus der Browsersprache — dieselbe Regel wie auf dem Server. Das HTML ist deutsch; wer Englisch bevorzugt, sieht nach der Hydration kurz den Wechsel [E]. Pfade mit Sprache (/en/…) hätten das vermieden, aber jede Seite, jeden Link und die Zonen verdoppelt.
• Angemeldet: Die Anmeldung setzt neben dem verschlüsselten kp_session (httpOnly) das lesbare Cookie kp_ui mit derselben Laufzeit (user oder pass); die Abmeldung löscht beide. Es enthält keine Identität und öffnet nichts — es entscheidet nur, welche Navigationseinträge der Browser zeigt; jede Seite dahinter prüft die echte Sitzung. Gewählt statt eines Aufrufs /auth/state, weil es ohne Anfrage an die Lambda auskommt. Folge: Sitzungen von vor dieser Änderung zeigen auf / bis zur nächsten Anmeldung „Anmelden“ [E].

Antwort-Header: Cache-Control: public, max-age=0, s-maxage=300 (setzt der Proxy statt Next.js' s-maxage=31536000, damit eine vergessene Invalidierung höchstens fünf Minuten alte Asset-Namen ausliefert), ETag, dazu Vary: rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch. Browser fragen jedes Mal nach, CloudFront darf fünf Minuten halten.

Was der Edge-Stack dafür braucht (Stand dieser Seite: noch nicht gebaut): eigene Cache-Behaviors für / und /pass/einloesen zum Shell-Ursprung mit einer Cache Policy, die den Origin-Header Cache-Control achtet (Min-TTL 0, Default-TTL 0, Max-TTL 300 s), keine Cookies und keine Header im Cache-Schlüssel, aber alle Query-Strings (Next.js unterscheidet die RSC-Anfragen beim Seitenwechsel über ?_rsc=…), GET/HEAD; dazu eine Invalidierung von / und /pass/einloesen bei jedem Deploy.

Quellen#

• CloudFront OAC für Lambda Function URLs (Payload-Hash bei PUT/POST): https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-restricting-access-to-lambda.html
• Next.js Multi-Zones: https://nextjs.org/docs/app/guides/multi-zones
• Next.js basePath: https://nextjs.org/docs/app/api-reference/config/next-config-js/basePath
• Next.js Content Security Policy (Nonce über Proxy, statische Seiten): https://nextjs.org/docs/app/guides/content-security-policy
• Next.js global-not-found.js bei mehreren Root-Layouts: https://nextjs.org/docs/app/api-reference/file-conventions/not-found
• CSP Level 3 (Nonce, Hash-Quellen): https://www.w3.org/TR/CSP3/
• CloudFront: Caching und Origin-Header Cache-Control: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Expiration.html
• Custom Elements (MDN): https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements
• Cookie-Attribut SameSite (MDN): https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value