<!-- status: canonical -->
<!-- lastReviewed: 2026-04-10 -->
<!-- verifiedAgainst: frontend_nyla (codebase audit 2026-04-07, post Automation Unification) -->

# 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, graphicalEditor, realestate, neutralization, teamsbot) |
| `components/` | Wiederverwendbar: FormGenerator, FolderTree, Navigation, UnifiedDataBar, FlowEditor (Graphical Editor), OnboardingAssistant |
| `hooks/` | useApiRequest (useApi.ts), 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: API-basiertes Language-Loading (`index.ts`, `types.ts`), keine statischen Locale-Files |
| `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, CommCoach und Graphical Editor 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` | Konsolidierter n8n-style Flow-Builder (Graphical Editor) mit 3-Column-Layout: [UDB + Chat/Tracing] [Canvas + Header] [Nodes] |
| `FlowCanvas` | Custom React Canvas fuer Workflow-Graph-Rendering mit Node-Highlighting (SSE Live-Tracing) |
| `RunTracingPanel` | Live-Tracing von Workflow-Runs via SSE mit Fallback-Polling |
| `EditorChatPanel` | AI Chat im Editor mit Drag&Drop-Dateianhang und Source-Picker |
| `CanvasHeader` | Workflow-Metadaten, Versioning (Draft/Publish/Archive), Save-as-Template, New-from-Template |
| `TemplatePicker` | Modal zur Auswahl von Workflow-Vorlagen beim Erstellen neuer Workflows |
| `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 **`MainLayout.tsx`** mit **`MandateNavigation`** (Sidebar) und `<Outlet />` (React Router).
- **Seiten-Mapping:** `pageRegistry.tsx` definiert `PAGE_REGISTRY` und `FEATURE_REGISTRY`; Seiten werden lazy geladen. `core/PageManager/` enthält ergänzende Infrastruktur (State Preservation, Lifecycle-Hooks).
- **i18n:** DB-backed via `LanguageContext` (`t()`-Hook). Sprachsets werden dynamisch via public API geladen (`GET /api/i18n/sets/{code}`). Key-Konvention: **Deutscher Klartext = Key**. Jeder neue/geänderte UI-Text MUSS mit `t('Deutscher Klartext')` getaggt werden. Variable Interpolation: `t('Text {var}', {var: 'Wert'})`. Fallback: Ziel-Set → `de`-Set → Key selbst. Keine statischen Locale-Files. Das xx-Basisset enthaelt sowohl UI-Keys (context="ui") als auch Gateway-Keys (context="api.*", "table.*") — beide werden per AI uebersetzt.
- **TextMultilingual:** Felder vom Typ `TextMultilingual` rendern dynamisch Eingabefelder fuer alle verfuegbaren Sprachen (aus `availableLanguages`). Keine hardcodierten Sprach-Codes. Sprachcodes folgen ISO 639-1 (en, de, fr, it, …).
- **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
- **i18n-Pflicht:** Jeder UI-Text (Label, Button, Placeholder, Tooltip, Fehlermeldung) MUSS mit `t('Deutscher Klartext')` getaggt werden. Hardcodierte deutsche Strings im JSX sind nicht erlaubt. Import: `const { t } = useLanguage();`
- 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 |
| `layouts/MainLayout.tsx` | Haupt-Shell mit MandateNavigation + Outlet |
| `config/pageRegistry.tsx` | PAGE_REGISTRY, FEATURE_REGISTRY, Lazy Imports |
| `core/PageManager/` | State Preservation, Lifecycle, Caching |
| `auth/authConfig`, `authProvider`, `ProtectedRoute` | MSAL, geschützte Routen |
| `contexts/*` | FileContext, PekContext, Toast, Workflow-Auswahl, etc. |
| `components/FlowEditor/editor/Automation2FlowEditor.tsx` | Haupt-Editor-Komponente (3-Column-Layout, State-Management) |
| `components/FlowEditor/editor/FlowCanvas.tsx` | Custom Canvas mit Node-Rendering, Connections, Highlighting; `CanvasNode` traegt `inputPorts`/`outputPorts` |
| `components/FlowEditor/nodes/frontendTypeRenderers/index.tsx` | `FRONTEND_TYPE_RENDERERS` Registry — generischer Renderer pro `FrontendType` statt pro Node-Typ |
| `components/FlowEditor/editor/NodeConfigPanel.tsx` | Generischer Config-Renderer via `FRONTEND_TYPE_RENDERERS` (kein `NODE_CONFIG_REGISTRY` mehr) |
| `components/FlowEditor/nodes/shared/graphUtils.ts` | `fromApiGraph`/`toApiGraph` serialisieren `inputPorts`/`outputPorts` auf `CanvasNode` |
| `components/FlowEditor/nodes/shared/DataPicker.tsx` | Schema-basierte Pfad-Aufloesung, Transit-Chain, System-Variablen-Sektion |
| `components/FlowEditor/context/Automation2DataFlowContext.tsx` | Stellt `portTypeCatalog` und `systemVariables` im Context bereit |
| `components/FlowEditor/editor/RunTracingPanel.tsx` | SSE Live-Push + Canvas-Highlighting fuer Workflow-Runs |
| `components/FlowEditor/editor/EditorChatPanel.tsx` | AI Chat mit Dateianhang (Drag&Drop) und Source-Picker |
| `components/FlowEditor/editor/CanvasHeader.tsx` | Versioning, Template-Management, Workflow-Aktionen |
| `components/FlowEditor/editor/TemplatePicker.tsx` | Template-Auswahl-Modal |
| `pages/views/graphicalEditor/GraphicalEditorPage.tsx` | Feature-Seite mit KeepAlive, URL-basiertem Workflow-Loading |
| `locales/index.ts`, `types.ts` | i18n: API-basiertes Language-Loading (DB-backed, keine statischen Files) |
| `providers/language/LanguageContext.tsx` | `t()`-Hook mit `{variable}`-Interpolation, Fallback-Kette, `availableLanguages` |
| `components/FormGenerator/FormGeneratorForm/FormGeneratorForm.tsx` | Rendert `frontend_type: multilingual` (TextMultilingual) dynamisch nach `availableLanguages`; Button „In alle Sprachen uebersetzen“ (KI via `POST /api/i18n/translate-field`) |
| `pages/admin/AdminLanguagesPage.tsx` | Admin-Seite: Sprachset-Verwaltung (CRUD, AI-Übersetzung, UI/API-Key-Counts) |
| `pages/admin/AdminLanguagesKeepAlive.tsx` | KeepAlive-Wrapper: Sprach-Seite bleibt persistent bei Seitenwechsel |

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