wiki/b-reference/frontend-nyla/architecture.md

Frontend Nyla -- Architektur

Überblick

Frontend Nyla ist eine React-Single-Page-Application (SPA) mit TypeScript und Vite. Routing über React Router; Schichten: Presentation (Pages, Components), Business Logic (Hooks, *Logic-Module), Data Access (api.ts, Feature-API-Module), Infrastructure (Contexts, Provider, Konfiguration). PageManager lädt Seiten dynamisch (Lazy Loading, State Preservation, Lifecycle-Hooks). Authentifizierung über Azure MSAL; HTTP über Axios mit Interceptors.

Technologie-Stack (Stand UI-Doku): React 19.x, Vite 5.x, TypeScript 5.8.x, React Router DOM 7.x, Axios, @azure/msal-browser / @azure/msal-react, Framer Motion, XState, CSS Modules, React Icons.

Ordnerstruktur (src/)

Ordner	Inhalt
pages/	Seiten: admin/, basedata/, billing/, settings/, views/ (workspace, commcoach, chatbot, trustee, automation)
components/	Wiederverwendbar: FormGenerator, FolderTree, Navigation, UnifiedDataBar, Automation2FlowEditor, OnboardingAssistant
hooks/	useApi, useFiles, useNavigation, useConfirm, usePrompt, useResizablePanels, etc.
contexts/	FileContext, PekContext, ToastContext, WorkflowSelectionContext
api/	API-Client (api.ts) und Feature-spezifische API-Module
core/	PageManager
layouts/	Layout-Komponenten
locales/	i18n
types/	TypeScript-Typen
utils/	Utility-Funktionen

Ergänzend typische Root-Dateien und Bereiche im Repo: main.tsx, App.tsx, api.ts (Root), auth/ (MSAL, ProtectedRoute), assets/ — Feature-Module unter components/ oft nach Muster: Haupt-.tsx, *.module.css, *Logic.tsx, *Types.ts, optional index.ts.

Wichtige UI-Komponenten

Komponente	Zweck
UnifiedDataBar (UDB)	Multi-Tab-Panel: Chats, Files, Sources — wird in Workspace und CommCoach genutzt
FormGenerator	Dynamische Formulare/Tabellen aus Backend-Attribut-Definitionen
FolderTree	Rekursiver Ordnerbaum mit Drag&Drop, Multi-Selection, Inline-Editing
MandateNavigation	Feature-Baum-Navigation mit Mandanten-Kontext
Automation2FlowEditor	n8n-style Flow-Builder für Automation2
WorkspacePage	AI-Workspace mit Chat, UDB, Agent-Streaming

Routing

• Einstieg: main.tsx rendert App.tsx mit Providern (z. B. Sprache, Auth) und React Router (Routes / Route).
• Geschützte Bereiche: Route-Guards (z. B. ProtectedRoute) prüfen Authentifizierung; Redirect bei fehlender Session.
• Haupt-App: Nach Login typischerweise ein Home-/Shell-Layout mit Sidebar und PageManager.
• Seiten-Mapping: PageManager + Konfiguration (z. B. pageConfigs) — lazy geladene Page-Komponenten, Sidebar-Metadaten, optional preserveState für Navigation ohne State-Verlust.
• i18n / Theme: global über Context; API-Requests mit Auth-Header (Interceptor in zentralem API-Client).

UI-Regeln

• Keine Browser-Dialoge (alert / confirm / prompt) — stattdessen useConfirm() und usePrompt() Hooks
• Alle internen Funktionen mit _ Prefix
• camelCase für Variablen und Funktionen

Schlüssel-Dateien

Datei / Bereich	Rolle
main.tsx	Application Entry Point
App.tsx	Root-Komponente, Router-Setup, Provider
api.ts (Root)	Axios-Instanz, Base URL, Token-Interceptor, 401-Handling
core/ / components/PageManager/	Dynamisches Laden, Animationen, Lifecycle, Caching
pageConfigs (o. ä.)	Lazy Imports, Sidebar-Einträge, Page-Metadaten
auth/authConfig, authProvider, ProtectedRoute	MSAL, geschützte Routen
contexts/*	FileContext, PekContext, Toast, Workflow-Auswahl, etc.
locales/*	Übersetzungen (z. B. de / en / fr)

Regeln / Invarianten

• Feature-Organisation: UI, Logic (*Logic), Types und CSS Modules pro Feature-Modul trennen; Exporte über index.ts wo üblich.
• Datenfluss: Pages → Feature-Komponenten → Hooks → useApi / API-Module → Gateway; Fehler nicht verschlucken, konsistente Backend-Fehlerdarstellung.
• Performance: Seiten lazy laden; bei konfigurierten Seiten State Preservation nutzen.
• Styling: CSS Modules, Theme über CSS-Variablen (Light/Dark) wo vorgesehen.
• Typisierung: TypeScript durchgängig; API-Response-Typen an den Grenzen definieren.
• Naming: Komponenten PascalCase, Hooks use*, interne Hilfsfunktionen _ + camelCase — kein snake_case in neuem Frontend-Code.