Web-App-Architektur
Lies zuerst web-craft. Lade nur die Referenzen, die die Aufgabe benötigt; Kit- und Framework-Adapter nur für das gewählte Kit und Framework.
Karte
| Thema | Referenz |
|---|---|
| Server- vs. Client-Komponenten, BFF, Umgebungsvariablen- und Geheimnisgrenzen | references/server-client.md |
| API-Schicht, Fehlermodell, State Ownership, Formulare, optimistisches UI, URL-Status | references/data-forms.md |
| Lade-, Fehler- und NotFound-Grenzen, Wiederholung, Offline, Skelett-Timing | references/states.md |
| i18n: Registry, Auflösung, URL, Kataloge, Formatierung, Backend-Header | references/i18n.md |
| RTL, logische Eigenschaften, richtungsabhängige Symbole, Portale | references/rtl.md |
| Authentifizierung, Autorisierung, XSS, CSRF, Cookies, Cache-Isolation, persönliche Daten | references/auth-security.md |
| Theme: Benutzereinstellung vs. angewendetes Theme, Systemänderungen, kein Flackern | references/theming.md |
| SEO für öffentliche Seiten | references/seo.md |
| GEO: Sichtbarkeit in KI-Suche und Assistenten | references/geo.md |
| Next.js App Router Adapter | references/fw-next.md |
| React + Vite Adapter | references/fw-vite.md |
| shadcn/ui Adapter | references/kit-shadcn.md |
| Ant Design Adapter | references/kit-antd.md |
| Material UI Adapter | references/kit-mui.md |
| Arbeit mit einem node-craft (oder OpenAPI) Backend | references/node-craft-contract.md |
| Offizielle Quellen und Prüfungsdaten | references/sources.md |
Allgemeingültige Regeln
- Grenzen nach Bedarf. Eine Komponente ist eine Client-Komponente, weil sie Interaktivität, Browser-APIs oder Client-Status benötigt, nicht standardmäßig. Halte interaktive Inseln klein. Importiere niemals serverseitigen Code, ORM-Clients oder Geheimnisse in Client-Code; eine öffentliche Umgebungsvariable ist kein Geheimnis.
- Eine API-Schicht. Ein Fetch-Client, ein typisiertes Fehlermodell, das nach stabilen Codes und Status unterschlüsselt ist, ein Authentifizierungsverhalten. Features bauen kein eigenes Fetch und Retry. Serverdaten leben in der Query-/Cache-Schicht, globaler Client-Status in einem kleinen Store oder Kontext, Formularstatus im Formular-Tool, lokaler UI-Status in der Komponente. Eine Mock-Quelle wird durch Konfiguration für Entwicklung und Tests aktiviert, niemals durch Bearbeiten von Features; nicht vertrauenswürdige Antworten werden zur Laufzeit geparst.
- Formulare. react-hook-form + Zod, sofern das Projekt kein anderes Tool verwendet.
mode: 'onTouched',reValidateMode: 'onChange', Fokus und Scrollen zum ersten Fehler, serverseitige Feld-Fehler übersetError, Werte bleiben nach Fehlern erhalten, doppeltes Absenden wird blockiert. Der Server bleibt die Autorität für die Validierung. - Zustände haben Grenzen. Routenweite Lade- und Fehlergrenzen sowie lokales Suspense, wo Daten gestreamt werden; ein fehlerhaftes Widget lässt nicht die gesamte Seite leer.
- i18n ist Architektur. Eine echte Engine, eine Locale-Registry (BCP 47-Tag, Richtung, Katalog, Anzeigename), Englisch als Fallback, sofern nicht anders gewählt, request-scoped Locale auf dem Server, dasselbe anfängliche Locale auf Server und Client, Kataloge werden pro Locale und Namespace geladen, Kit- und Datums-Locale werden vom App-Locale abgebildet.
- Sicherheit ist serverseitig. Autorisierung im Backend. Säubere jedes gerenderte HTML. Cookie-Sitzungen benötigen CSRF-Schutz. Persönliche Antworten werden niemals in einen gemeinsamen Cache gelegt; locale- und benutzerabhängige Antworten variieren ihre Cache-Schlüssel.
- Öffentliche Seiten sind auffindbar. Locale-korrekte Metadaten, die auf dem Server gerendert werden, kanonische URLs pro Sprache, hreflang-Alternativen nur für echte Gegenstücke, Sitemap, strukturierte Daten, die dem sichtbaren Inhalt entsprechen. GEO beginnt damit: indexierbare, zitierbare Inhalte und eine explizite KI-Crawler-Richtlinie. Keine Ranking- oder Zitierungsgarantien.
- Kits werden adaptiert, nicht umwickelt. Theme und Tokens stammen aus den Designentscheidungen des Produkts. Wickle eine Kit-Komponente nur für wiederholtes Produktverhalten oder zur Fixierung einer API ein. Staple kein zweites Animationssystem auf die eigenen Übergänge eines Kits.
Erledigt
web-craft anwenden → erledigt, plus: kein Client-Bundle enthält ein Geheimnis oder ein serverseitiges Modul; zwei gleichzeitige Anfragen in unterschiedlichen Locales oder für unterschiedliche Benutzer können keine Daten vermischen; das erste Rendering erfolgt in der richtigen Sprache und mit dem richtigen Theme; jede behauptete Kit-/Framework-Kombination wurde tatsächlich überprüft.