92 lines
7 KiB
Markdown
92 lines
7 KiB
Markdown
<!-- status: canonical -->
|
|
<!-- lastReviewed: 2026-04-08 -->
|
|
<!-- 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.
|
|
- **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 |
|
|
| `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` |
|
|
| `pages/admin/AdminLanguagesPage.tsx` | Admin-Seite: Sprachset-Verwaltung (CRUD, AI-Übersetzung) |
|
|
|
|
## 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.
|