PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/ui_nyla/README.md
ValueOn AG 9c3af697ec nyla doc
2025-12-16 00:27:41 +01:00

24 KiB
Raw Blame History

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