76 lines
4.7 KiB
Markdown
76 lines
4.7 KiB
Markdown
<!-- status: canonical -->
|
|
<!-- lastReviewed: 2026-04-05 -->
|
|
<!-- verifiedAgainst: frontend_nyla (codebase audit 2026-04-05) -->
|
|
|
|
# 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, automation2, realestate, neutralization, teamsbot) |
|
|
| `components/` | Wiederverwendbar: FormGenerator, FolderTree, Navigation, UnifiedDataBar, Automation2FlowEditor, 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 |
|
|
| `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 **`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 / 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 |
|
|
| `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. |
|
|
| `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.
|