# Frontend Nyla - UI Dokumentation

## Übersicht

Das Frontend Nyla ist eine React-basierte Single-Page-Application (SPA), die mit TypeScript entwickelt wurde. Die Anwendung verwendet Vite als Build-Tool und React Router für das Routing. Die Architektur folgt einem modularen Ansatz mit klarer Trennung von Komponenten, Hooks, Seiten und Geschäftslogik.

---

## 1. Architektur

### 1.1 Architektur-Übersicht

Die Anwendung folgt einer **layered architecture** mit folgenden Ebenen:

```
┌─────────────────────────────────────────────────────────┐
│                    Presentation Layer                   │
│  (Pages, Components, UI Elements)                       │
├─────────────────────────────────────────────────────────┤
│                    Business Logic Layer                 │
│  (Hooks, Logic Files, State Management)                 │
├─────────────────────────────────────────────────────────┤
│                    Data Access Layer                    │
│  (API Client, Authentication)                           │
├─────────────────────────────────────────────────────────┤
│                    Infrastructure Layer                 │
│  (Contexts, Providers, Configuration)                   │
└─────────────────────────────────────────────────────────┘
```

### 1.2 Kern-Architektur-Prinzipien

#### 1.2.1 Component-Based Architecture
- **Komponenten** sind in Feature-Module organisiert
- Jedes Feature-Modul enthält:
  - UI-Komponenten (`.tsx`)
  - Styles (`.module.css`)
  - Geschäftslogik (`*Logic.tsx`)
  - Type-Definitionen (`*Types.ts`, `*Interfaces.ts`)
  - Index-Dateien für saubere Exports

#### 1.2.2 Custom Hooks Pattern
- Geschäftslogik wird in wiederverwendbare Hooks extrahiert
- Hooks kapseln API-Aufrufe und State-Management
- Beispiel: `useWorkflows`, `useFiles`, `useConnections`

#### 1.2.3 Page Management System
- **PageManager** verwaltet dynamisches Laden und Caching von Seiten
- Unterstützt:
  - Lazy Loading für bessere Performance
  - State Preservation für bestimmte Seiten
  - Lifecycle-Hooks (onActivate, onDeactivate, onLoad, onUnload)
  - Animations-basierte Seitenübergänge

#### 1.2.4 Context API für Global State
- **LanguageContext**: Internationalisierung (i18n)
- **AuthProvider**: Azure MSAL-basierte Authentifizierung

### 1.3 Technologie-Stack

- **Framework**: React 19.1.0
- **Build Tool**: Vite 5.4.10
- **Language**: TypeScript 5.8.3
- **Routing**: React Router DOM 7.7.1
- **State Management**: React Hooks + Context API
- **HTTP Client**: Axios 1.8.3
- **Authentication**: Azure MSAL (@azure/msal-browser, @azure/msal-react)
- **Animations**: Framer Motion 12.7.3
- **State Machine**: XState 5.20.1
- **Styling**: CSS Modules
- **Icons**: React Icons 5.5.0

### 1.4 Authentifizierung & Sicherheit

- **Azure MSAL Integration**: OAuth2/OIDC-basierte Authentifizierung
- **Protected Routes**: Route-Guards für geschützte Bereiche
- **Token Management**: Automatische Token-Erneuerung und -Validierung
- **API Interceptors**: Automatisches Hinzufügen von Authorization-Headern

### 1.5 Internationalisierung (i18n)

- Unterstützte Sprachen: Deutsch (de), Englisch (en), Französisch (fr)
- Dynamisches Laden von Übersetzungen
- Browser-Sprache-Erkennung
- Persistierung der Sprachauswahl in localStorage

---

## 2. Struktur

### 2.1 Verzeichnisstruktur

```
frontend_nyla/
├── src/
│   ├── api.ts                          # Zentraler API-Client (Axios)
│   ├── App.tsx                         # Root-Komponente mit Routing
│   ├── main.tsx                        # Application Entry Point
│   ├── index.css                      # Global Styles
│   │
│   ├── auth/                          # Authentifizierung
│   │   ├── authConfig.ts              # MSAL Konfiguration
│   │   ├── authProvider.tsx          # MSAL Provider Component
│   │   └── ProtectedRoute.tsx        # Route Guard Component
│   │
│   ├── components/                    # Wiederverwendbare Komponenten
│   │   ├── Connections/               # Connections Feature Module
│   │   ├── Dashboard/                 # Dashboard Feature Module
│   │   │   └── DashboardChat/        # Chat-Komponente mit Sub-Komponenten
│   │   ├── Dateien/                   # Dateien Feature Module
│   │   ├── FilePreview/               # File Preview mit Renderers
│   │   ├── FormGenerator/             # Dynamischer Form-Generator
│   │   ├── Mitglieder/                # Mitglieder Feature Module
│   │   ├── PageManager/               # Seiten-Management System
│   │   ├── Popup/                     # Modal/Popup Komponenten
│   │   ├── Prompts/                   # Prompts Feature Module
│   │   ├── Sidebar/                   # Sidebar Navigation
│   │   ├── TestSharepoint/            # SharePoint Test Feature
│   │   └── Workflows/                 # Workflows Feature Module
│   │
│   ├── contexts/                      # React Contexts
│   │   └── LanguageContext.tsx        # i18n Context
│   │
│   ├── hooks/                         # Custom React Hooks
│   │   ├── useApi.ts                  # Generic API Request Hook
│   │   ├── useAuthentication.ts       # Auth Hooks
│   │   ├── useConnections.ts          # Connections Hooks
│   │   ├── useFiles.ts                # Files Hooks
│   │   ├── usePrompts.ts              # Prompts Hooks
│   │   ├── useSharePointTest.ts       # SharePoint Test Hooks
│   │   ├── useSidebar.ts              # Sidebar Hooks
│   │   ├── useUsers.ts                # Users Hooks
│   │   └── useWorkflows.ts            # Workflows Hooks
│   │
│   ├── locales/                       # Übersetzungen
│   │   ├── de.ts                      # Deutsche Übersetzungen
│   │   ├── en.ts                      # Englische Übersetzungen
│   │   ├── fr.ts                      # Französische Übersetzungen
│   │   ├── index.ts                   # Locale Loader
│   │   └── types.ts                   # Type Definitions
│   │
│   ├── pages/                         # Seiten-Komponenten
│   │   ├── Login.tsx                  # Login-Seite
│   │   ├── Register.tsx               # Registrierungs-Seite
│   │   └── Home/                      # Haupt-Anwendungsbereich
│   │       ├── Home.tsx               # Home Container
│   │       ├── Dashboard.tsx          # Dashboard-Seite
│   │       ├── Dateien.tsx            # Dateien-Seite
│   │       ├── Connections.tsx        # Connections-Seite
│   │       ├── Workflows.tsx          # Workflows-Seite
│   │       ├── Prompts.tsx            # Prompts-Seite
│   │       ├── TeamBereich.tsx        # Team-Bereich-Seite
│   │       ├── Einstellungen.tsx      # Einstellungen-Seite
│   │       ├── TestSharepoint.tsx     # SharePoint Test-Seite
│   │       └── HomeStyles/            # Seiten-spezifische Styles
│   │
│   └── assets/                        # Statische Assets
│       └── styles/
│           ├── light.css              # Light Theme CSS Variables
│           └── dark.css               # Dark Theme CSS Variables
│
├── public/                            # Öffentliche Assets
├── documentation/                     # Dokumentation
├── .env.dev                          # Development Environment Variables
├── .env.int                          # Integration Environment Variables
├── .env.prod                         # Production Environment Variables
├── vite.config.ts                    # Vite Konfiguration
├── tsconfig.json                     # TypeScript Konfiguration
└── package.json                      # Dependencies & Scripts
```

### 2.2 Feature-Module Struktur

Jedes Feature-Modul folgt einem konsistenten Muster:

```
FeatureModule/
├── ComponentName.tsx                  # Haupt-Komponente
├── ComponentName.module.css          # Komponenten-Styles
├── featureLogic.tsx                  # Geschäftslogik
├── featureTypes.ts                   # TypeScript Types
├── featureInterfaces.ts              # TypeScript Interfaces (optional)
└── index.ts                          # Public API Export
```

**Beispiel: Connections Module**
```
Connections/
├── ConnectionsTable.tsx              # Haupt-Tabellen-Komponente
├── ConnectionsTable.module.css      # Tabellen-Styles
├── ConnectionEditModal.tsx          # Edit-Modal Komponente
├── ConnectionEditModal.module.css   # Modal-Styles
├── ConnectionsErrorDisplay.tsx      # Error-Display Komponente
├── ConnectionsErrorDisplay.module.css
├── connectionsLogic.tsx              # Geschäftslogik
├── connectionsInterfaces.ts         # Type Definitions
└── index.ts                          # Exports
```

### 2.3 Seiten-Struktur

Seiten sind in `pages/Home/` organisiert und verwenden:
- **Shared Styles**: `pages.module.css` für gemeinsame Seiten-Styles
- **Feature Components**: Importieren entsprechende Komponenten aus `components/`
- **Hooks**: Nutzen Custom Hooks für Daten-Fetching und State-Management
- **Language Context**: Nutzen `useLanguage()` für i18n

### 2.4 Naming Conventions

- **Komponenten**: PascalCase (z.B. `DashboardChat.tsx`)
- **Hooks**: camelCase mit "use" Prefix (z.B. `useWorkflows.ts`)
- **Logic Files**: camelCase mit "Logic" Suffix (z.B. `connectionsLogic.tsx`)
- **Types/Interfaces**: camelCase mit "Types"/"Interfaces" Suffix
- **CSS Modules**: `.module.css` Suffix
- **Internal Functions**: Prefix mit `_` (z.B. `_internalFunction()`)

---

## 3. Dependency Map

### 3.1 Dependency Graph - High Level

```
main.tsx
  └── App.tsx
      ├── LanguageProvider (contexts/LanguageContext.tsx)
      ├── AuthProvider (auth/authProvider.tsx)
      └── Router (react-router-dom)
          ├── Login (pages/Login.tsx)
          ├── Register (pages/Register.tsx)
          └── Home (pages/Home/Home.tsx)
              ├── Sidebar (components/Sidebar/)
              └── PageManager (components/PageManager/)
                  └── [Lazy Loaded Pages]
```

### 3.2 Core Dependencies

#### 3.2.1 Application Entry Point

**main.tsx**
- Abhängigkeiten: `react`, `react-dom`, `App.tsx`
- Verantwortlichkeit: React Root erstellen und App rendern

**App.tsx**
- Abhängigkeiten:
  - `react-router-dom` (Router, Routes, Route)
  - `contexts/LanguageContext` (LanguageProvider)
  - `auth/authProvider` (AuthProvider)
  - `auth/ProtectedRoute` (ProtectedRoute)
  - `pages/Login` (Login)
  - `pages/Register` (Register)
  - `pages/Home/Home` (Home)
- Verantwortlichkeit: Routing-Setup, Provider-Wrapper, Theme-Management

#### 3.2.2 Authentication Layer

**auth/authProvider.tsx**
- Abhängigkeiten:
  - `@azure/msal-browser` (PublicClientApplication, AuthenticationResult)
  - `@azure/msal-react` (MsalProvider)
  - `auth/authConfig` (msalConfig)
- Verantwortlichkeit: MSAL Initialisierung, Account Management

**auth/ProtectedRoute.tsx**
- Abhängigkeiten:
  - `react-router-dom` (Navigate)
  - `hooks/useAuthentication` (useAuth)
- Verantwortlichkeit: Route Protection, Redirect bei fehlender Authentifizierung

#### 3.2.3 API Layer

**api.ts**
- Abhängigkeiten: `axios`
- Verantwortlichkeit:
  - Axios Instance mit Base URL
  - Request Interceptor (Token Injection)
  - Response Interceptor (401 Handling, Redirect)

**hooks/useApi.ts**
- Abhängigkeiten: `api.ts`
- Verantwortlichkeit: Generic API Request Hook mit Error Handling

### 3.3 Component Dependencies

#### 3.3.1 PageManager System

**components/PageManager/PageManager.tsx**
- Abhängigkeiten:
  - `react-router-dom` (useLocation)
  - `framer-motion` (motion, AnimatePresence)
  - `components/PageManager/pageConfigs` (pageConfigs)
- Verantwortlichkeit:
  - Dynamisches Laden von Seiten
  - State Preservation
  - Page Lifecycle Management
  - Animations

**components/PageManager/pageConfigs.ts**
- Abhängigkeiten:
  - `react` (lazy)
  - `components/PageManager/pageConfigInterface` (PageConfig)
  - Alle Page-Komponenten (lazy loaded)
- Verantwortlichkeit: Seiten-Konfiguration, Sidebar-Metadaten

#### 3.3.2 Sidebar System

**components/Sidebar/Sidebar.tsx**
- Abhängigkeiten:
  - `components/Sidebar/SidebarItem` (SidebarItem)
  - `components/Sidebar/SidebarUser` (SidebarUser)
  - `hooks/useSidebar` (useSidebarFromPageConfigs)
  - `components/Sidebar/sidebarLogic` (useSidebarLogic)
- Verantwortlichkeit: Sidebar Container, Navigation Rendering

**hooks/useSidebar.ts**
- Abhängigkeiten:
  - `components/PageManager/pageConfigs` (getSidebarItems)
- Verantwortlichkeit: Sidebar-Daten aus Page-Configs extrahieren

#### 3.3.3 Dashboard & Workflow System

**pages/Home/Dashboard.tsx**
- Abhängigkeiten:
  - `components/Dashboard/DashboardChat` (DashboardChat)
  - `hooks/useWorkflows` (useWorkflows)
  - `components/Dashboard/DashboardChat/useWorkflowManager` (useWorkflowManager)
  - `contexts/LanguageContext` (useLanguage)
- Verantwortlichkeit: Dashboard-Seite, Workflow-Management

**components/Dashboard/DashboardChat/DashboardChat.tsx**
- Abhängigkeiten:
  - `components/Dashboard/DashboardChat/DashboardChatArea` (DashboardChatArea)
- Verantwortlichkeit: Chat Container

**components/Dashboard/DashboardChat/useWorkflowManager.ts**
- Abhängigkeiten:
  - `hooks/useWorkflows` (useWorkflow, useWorkflowStatus, useWorkflowMessages, useWorkflowLogs, useWorkflowOperations)
  - `components/Dashboard/DashboardChat/dashboardChatAreaTypes` (WorkflowState, WorkflowActions)
- Verantwortlichkeit: Workflow State Management, Polling Logic, Optimistic Updates

**hooks/useWorkflows.ts**
- Abhängigkeiten:
  - `hooks/useApi` (useApiRequest)
  - `components/Dashboard/DashboardChat/dashboardChatAreaTypes` (Workflow Types)
- Verantwortlichkeit: Workflow API Calls, Data Fetching

### 3.4 Feature Module Dependencies

#### 3.4.1 Connections Module

**components/Connections/ConnectionsTable.tsx**
- Abhängigkeiten:
  - `components/Connections/connectionsLogic` (useConnectionsLogic)
  - `components/Connections/ConnectionEditModal` (ConnectionEditModal)
  - `components/Connections/ConnectionsErrorDisplay` (ConnectionsErrorDisplay)
  - `hooks/useConnections` (useConnections)
  - `contexts/LanguageContext` (useLanguage)

**hooks/useConnections.ts**
- Abhängigkeiten:
  - `hooks/useApi` (useApiRequest)
  - `components/Connections/connectionsInterfaces` (Connection Types)

#### 3.4.2 Files Module

**components/Dateien/DateienTable.tsx**
- Abhängigkeiten:
  - `components/Dateien/dateienLogic` (useDateienLogic)
  - `components/FilePreview` (FilePreview)
  - `hooks/useFiles` (useFiles, useFileOperations)
  - `contexts/LanguageContext` (useLanguage)

**hooks/useFiles.ts**
- Abhängigkeiten:
  - `hooks/useApi` (useApiRequest)

**components/FilePreview/FilePreview.tsx**
- Abhängigkeiten:
  - `components/FilePreview/renderers/*` (Verschiedene Renderer)
- Verantwortlichkeit: File-Type Detection, Renderer Selection

#### 3.4.3 Prompts Module

**components/Prompts/PromptsTable.tsx**
- Abhängigkeiten:
  - `components/Prompts/promptsLogic` (usePromptsLogic)
  - `components/Popup` (Popup, EditForm)
  - `hooks/usePrompts` (usePrompts, usePromptOperations)
  - `contexts/LanguageContext` (useLanguage)

**hooks/usePrompts.ts**
- Abhängigkeiten:
  - `hooks/useApi` (useApiRequest)

### 3.5 Context Dependencies

**contexts/LanguageContext.tsx**
- Abhängigkeiten:
  - `locales/index` (loadLanguage)
  - `locales/types` (Language, TranslationKeys)
- Verantwortlichkeit: i18n State Management, Translation Loading

**locales/index.ts**
- Abhängigkeiten:
  - `locales/de` (deutsche Übersetzungen)
  - `locales/en` (englische Übersetzungen)
  - `locales/fr` (französische Übersetzungen)
- Verantwortlichkeit: Dynamisches Laden von Übersetzungen

### 3.6 Dependency Flow Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                        Pages Layer                          │
│  (Dashboard, Dateien, Connections, Workflows, etc.)         │
└────────────┬───────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────┐
│                    Components Layer                         │
│  (Feature Components, UI Components)                       │
└────────────┬───────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────┐
│                      Hooks Layer                            │
│  (useWorkflows, useFiles, useConnections, etc.)            │
└────────────┬───────────────────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────────────────────┐
│                      API Layer                              │
│  (useApi.ts → api.ts → Backend)                            │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    Infrastructure Layer                     │
│  (Contexts, Providers, Configuration)                      │
│                                                             │
│  LanguageContext ──→ locales/                              │
│  AuthProvider ──→ @azure/msal-*                            │
│  PageManager ──→ pageConfigs ──→ Lazy Pages                │
└─────────────────────────────────────────────────────────────┘
```

### 3.7 External Dependencies

#### React Ecosystem
- `react`, `react-dom`: Core React Library
- `react-router-dom`: Client-side Routing
- `@azure/msal-browser`, `@azure/msal-react`: Azure Authentication

#### UI & Styling
- `framer-motion`: Animations
- `react-icons`: Icon Library
- CSS Modules: Scoped Styling

#### State Management
- `xstate`, `@xstate/react`: State Machine (für komplexe Workflows)

#### HTTP & Data
- `axios`: HTTP Client
- `jwt-decode`: JWT Token Decoding

#### Utilities
- `js-cookie`: Cookie Management
- `react-dropzone`: File Upload

### 3.8 Critical Dependency Paths

#### Authentication Flow
```
App.tsx
  └── AuthProvider
      └── ProtectedRoute
          └── Home
              └── [All Protected Pages]
```

#### Data Fetching Flow
```
Page Component
  └── Feature Component
      └── Custom Hook (useWorkflows, useFiles, etc.)
          └── useApiRequest
              └── api.ts (Axios)
                  └── Backend API
```

#### Page Loading Flow
```
App.tsx
  └── Router
      └── Home
          └── PageManager
              └── pageConfigs
                  └── Lazy Component
                      └── Page Component
```

#### Internationalization Flow
```
App.tsx
  └── LanguageProvider
      └── [All Components]
          └── useLanguage()
              └── locales/[lang].ts
```

---

## 4. Wichtige Architektur-Entscheidungen

### 4.1 Lazy Loading
- Seiten werden lazy geladen für bessere Initial Load Performance
- Implementiert via `React.lazy()` in `pageConfigs.ts`

### 4.2 State Preservation
- Dashboard-Seite behält State bei Navigation
- Implementiert via `preserveState` Flag in PageConfig
- PageManager verwaltet preserved Instances separat

### 4.3 CSS Modules
- Scoped Styling für bessere Isolation
- Konfiguriert in `vite.config.ts`

### 4.4 Error Handling
- Zentralisiertes Error Handling in `useApi.ts`
- Formatierung von Backend-Errors für konsistente UX

### 4.5 Theme Management
- CSS Variables für Light/Dark Theme
- Persistierung in localStorage
- Automatische Browser-Präferenz-Erkennung

---

## 5. Entwicklung & Build

### 5.1 Development Scripts
- `npm run dev`: Development Server (Port 5176, Mode: dev)
- `npm run dev:prod`: Development mit Production Environment
- `npm run dev:int`: Development mit Integration Environment

### 5.2 Build Scripts
- `npm run build`: Standard Build
- `npm run build:prod`: Production Build
- `npm run build:int`: Integration Build

### 5.3 Environment Variables
- Präfix: `VITE_`
- Konfiguriert in `.env.dev`, `.env.int`, `.env.prod`
- Zugriff via `import.meta.env.VITE_*`

---

## 6. Best Practices & Patterns

### 6.1 Component Organization
- Feature-basierte Organisation
- Separation of Concerns (UI, Logic, Types)
- Index-Dateien für saubere Exports

### 6.2 Hook Patterns
- Custom Hooks für wiederverwendbare Logik
- API-Hooks nutzen `useApiRequest` für Konsistenz
- State Management in Hooks, nicht in Components

### 6.3 Type Safety
- TypeScript für alle Dateien
- Zentrale Type-Definitionen in Feature-Modulen
- Interfaces für API-Responses

### 6.4 Code Style
- camelCase für Variablen und Funktionen
- PascalCase für Komponenten
- `_` Prefix für interne Funktionen
- Keine snake_case

---

## 7. Erweiterungen & Wartung

### 7.1 Neue Seite hinzufügen
1. Page-Komponente in `pages/Home/` erstellen
2. Lazy Import in `pageConfigs.ts` hinzufügen
3. PageConfig mit Metadaten erstellen
4. Bei Bedarf Feature-Komponenten erstellen

### 7.2 Neues Feature-Modul hinzufügen
1. Verzeichnis in `components/` erstellen
2. Komponenten, Logic, Types, Styles hinzufügen
3. Index-Datei für Exports erstellen
4. Custom Hook in `hooks/` erstellen (falls API-Calls benötigt)

### 7.3 Neue API-Endpoints integrieren
1. Hook in `hooks/` erstellen oder erweitern
2. `useApiRequest` nutzen für API-Calls
3. Types für Request/Response definieren
4. Error Handling implementieren

---

## 8. Anhang

### 8.1 Abkürzungen
- **SPA**: Single-Page Application
- **MSAL**: Microsoft Authentication Library
- **i18n**: Internationalization
- **API**: Application Programming Interface
- **CSS**: Cascading Style Sheets
- **TSX**: TypeScript XML (React Components)

### 8.2 Wichtige Dateien Referenz
- `main.tsx`: Application Entry Point
- `App.tsx`: Root Component & Routing
- `api.ts`: API Client Configuration
- `components/PageManager/pageConfigs.ts`: Seiten-Konfiguration
- `contexts/LanguageContext.tsx`: i18n Context
- `auth/authProvider.tsx`: Authentication Provider

---

*Dokumentation erstellt: 2025-01-15*
*Version: 1.0*