# PowerOn Frontend Architektur & Spezifikation

## 1. Funktionsumfang des Frontends

Das Frontend der PowerOn-Plattform bietet folgende Kernfunktionen:

- **Multi-Agent Chat-Workflow**: Interaktive Chat-Oberfläche für die Steuerung von Workflows mit mehreren KI-Agenten.
- **Datei-Upload & -Verwaltung**: Nutzer können Dateien hochladen, anhängen, einsehen und herunterladen.
- **Prompt-Verwaltung**: Verwaltung und Nutzung von Prompt-Vorlagen für wiederkehrende Aufgaben.
- **Log- und Statusanzeige**: Fortschrittsanzeige, Fehler- und Statusmeldungen für Workflows.
- **Benutzer- und Mandantenverwaltung**: Admin-Funktionen zur Verwaltung von Usern und Mandanten.
- **Dynamische Datentabellen**: CRUD-Operationen (Create, Read, Update, Delete) für beliebige Entitäten über generische Tabellen und Formulare.
- **Authentifizierung**: Login via klassischem Account oder Microsoft-Account.

## 2. Struktur des Frontends

Das Frontend ist modular aufgebaut und besteht aus folgenden Hauptmodulen und -bereichen:

- **js/main.js**: Einstiegspunkt, Initialisierung der App und Navigation.
- **js/shared/**: Gemeinsame Module für State-Management, API-Calls, Navigation, Utilities, Authentifizierung, Formulargenerierung.
    - **globalState.js**: Zentrale State-Verwaltung und Navigation.
    - **apiCalls.js**: Konsolidierte Schnittstelle für Backend-Kommunikation.
    - **formGeneric.js**: Generisches Modul für CRUD-Tabellen und Formulare.
    - **msftCalls.js**: Microsoft-Authentifizierung und Status.
    - **navigation.js**: Dynamische Navigation und Menü-Rendering.
    - **utils.js**: Hilfsfunktionen (z.B. Toasts, UI-Feedback).
- **js/modules/**: Feature-spezifische Module (z.B. prompts.js, users.js, files.js).
- **public/htmlparts/**: HTML-Teile und Stylesheets für Layout, Navigation, Workflow, Formulare.
- **public/docu/**: Dokumentation und Spezifikationen.

## 3. Kommunikation mit dem Backend

Die gesamte Kommunikation mit dem Backend erfolgt konsolidiert über das Modul **apiCalls.js**. Dieses Modul bietet Funktionen für alle relevanten API-Endpunkte:

- **Workflows**: Starten, Fortsetzen, Stoppen, Status, Logs, Nachrichten, Löschen
- **Dateien**: Upload, Download, Löschen, Anhängen/Entfernen an Nachrichten
- **Prompts**: CRUD-Operationen für Prompt-Vorlagen
- **User/Mandanten**: Verwaltung von Benutzern und Mandanten
- **Generische Entitäten**: CRUD für beliebige Datentabellen

Alle API-Aufrufe sind asynchron und liefern Promises zurück. Fehlerbehandlung und Statusmeldungen werden zentral im Modul und über UI-Feedback (Toasts) gehandhabt.

## 4. Workflow-States (State Machine)

Die States eines Workflows sind in den Dateien @doc_statemachine_backend.md und @doc_statemachine_frontend.md ausführlich beschrieben. Die wichtigsten States sind:

- **null**: Kein Workflow aktiv
- **running**: Workflow läuft, Polling aktiv
- **completed**: Workflow abgeschlossen, UI bereit für neue Eingabe
- **failed**: Fehler aufgetreten, UI zeigt Fehler und Retry-Option
- **stopped**: Workflow wurde gestoppt, UI bietet Fortsetzen/Reset

Transitions und State-Änderungen werden sowohl im Backend als auch im Frontend synchronisiert und über Polling-Mechanismen aktuell gehalten.

## 5. Administrierung von Usern, Mandanten und Datentabellen

Die Administration erfolgt konsolidiert über das generische Modul **formGeneric.js**:

- **User- und Mandantenverwaltung**: CRUD-Tabellen und Formulare für Benutzer und Mandanten, inklusive Rechteverwaltung.
- **Datentabellen**: Beliebige Entitäten (z.B. Prompts, Dateien, Workflows) können als Tabelle mit Formularen verwaltet werden.
- **Features**:
    - Tabellenansicht mit Filter, Sortierung, Pagination, Massenaktionen
    - Formulare für Erstellen/Bearbeiten mit dynamischer Feldgenerierung
    - Validierung und Transformation der Formulardaten
    - Externe Buttons für "+ Neuen ... erstellen" können einfach angebunden werden
    - Felder, die mit "_" beginnen oder Zeitstempel wie "created_at" werden automatisch ausgeblendet

## 6. Implementierung & Datenstruktur für das formGeneric Modul

**Hinweis:** Die folgenden Beispiele und Erklärungen beziehen sich exemplarisch auf die Tabelle **"prompt"**. Das Prinzip ist jedoch für alle mit formGeneric verwalteten Entitäten identisch.

### Was macht das Modul formGeneric?

Das Modul **formGeneric.js** stellt eine generische Lösung für die Verwaltung beliebiger Datentabellen im Frontend bereit. Es übernimmt:

- Das Laden, Anzeigen, Erstellen, Bearbeiten und Löschen (CRUD) von Datensätzen
- Die dynamische Generierung von Tabellen und Formularen anhand der gelieferten Datenstruktur
- Die Filterung, Sortierung, Paginierung und Massenaktionen in der Tabellenansicht
- Die Validierung und Transformation von Formulardaten (optional)
- Die Anbindung externer Buttons (z.B. "+ Neuen Prompt erstellen")
- Die automatische Ausblendung von Feldern, die mit "_" beginnen oder Zeitstempel wie "created_at" enthalten
- Die Berücksichtigung von Berechtigungen: Felder wie `_hideEdit`, `_hideDelete`, `_hideView` steuern, ob die jeweiligen Aktionen für einen Datensatz im UI angezeigt werden
- Die Rendering-Logik: Längere Felder wie "content" oder "description" werden als Textarea dargestellt, boolesche Felder als Checkbox, numerische Felder als Zahlenfeld
- Die dynamische Anpassung an die Datenstruktur: Die Felder werden aus dem ersten Element der Datenliste abgeleitet

### Immer vorhandene/unterstützte Parameter (pro Datensatz)

- **id**: Eindeutige ID des Datensatzes (wird immer angezeigt)
- **_**-Felder: Interne Felder, die mit "_" beginnen, werden in Tabellen und Formularen ausgeblendet
- **createdAt, updatedAt, created_at**: Zeitstempel werden automatisch ausgeblendet
- **_hideEdit, _hideDelete, _hideView**: Steuern, ob die jeweiligen Aktionen (Bearbeiten, Löschen, Anzeigen) im UI für diesen Datensatz angezeigt werden
- **Weitere Felder**: Werden dynamisch als Spalten und Formularfelder generiert, sofern sie nicht explizit ausgeschlossen sind

### Integration

Das Modul wird wie folgt initialisiert:

```js
window.genericEntityModule.init(globalState, {
    entityType: 'prompt', // oder 'user', 'mandate', ...
    apiEndpoint: {
        get: api.getPrompts,
        create: api.createPrompt,
        update: api.updatePrompt,
        delete: api.deletePrompt
    },
    listContainerId: 'prompts-list',
    addButtonId: 'add-prompt-btn',
    transformFormData: function(formData) { /* optional */ },
    onItemCreated: function(item) { /* optional */ },
    onItemUpdated: function(item) { /* optional */ },
    onItemDeleted: function(id) { /* optional */ }
});
```

### Erwartete Datenstruktur (aus der Route/API)

Das Modul erwartet, dass die API-Endpoints Objekte mit folgender Struktur liefern (Beispiel Prompt):

```json
{
  "id": 123,
  "name": "Prompt-Name",
  "description": "Beschreibung",
  "content": "Prompt-Inhalt",
  "createdAt": "2024-05-11T12:34:56Z",
  "updatedAt": "2024-05-11T12:34:56Z",
  "_internal": "...", // wird ignoriert
  "_hideEdit": false,   // steuert Bearbeiten-Button
  "_hideDelete": false, // steuert Löschen-Button
  "_hideView": false    // steuert Anzeigen-Button
}
```

- Felder mit "_" am Anfang sowie Zeitstempel wie "createdAt", "updatedAt", "created_at" werden automatisch in Tabellen und Formularen ausgeblendet.
- Die Felder werden dynamisch aus dem ersten Element der Datenliste generiert.
- Für längere Felder wie "content" oder "description" wird automatisch ein Textarea verwendet.
- Checkboxen für boolesche Felder, Zahlenfelder für numerische Werte.
- Die Sichtbarkeit von Aktionen (Bearbeiten, Löschen, Anzeigen) wird pro Datensatz über die _hide*-Felder gesteuert.

### Erweiterbarkeit

- Das Modul kann für beliebige Entitäten verwendet werden, solange die API die Standard-CRUD-Methoden bereitstellt.
- Zusätzliche Aktionen (z.B. "Vorschau", "Spezial-Buttons") können über die Option `getItemActions` ergänzt werden.
- Die UI ist vollständig dynamisch und passt sich der gelieferten Datenstruktur an.

---

## 7. Workflow-UI: Darstellung und Datenfluss

Das Workflow-Modul im Frontend bildet die zentrale Chat- und Prozessansicht ab. Die wichtigsten UI-Elemente und deren Datenquellen sind:

- **Chatbereich**: Zeigt alle Nachrichten (user, agent, system) als Chat-Bubbles an. Die Nachrichten werden aus dem Backend über `/api/workflows/{workflowId}/messages` geladen und enthalten:
    - `content`: Text der Nachricht
    - `role`: user, assistant, agentName
    - `documents`: Anhänge (Dateien, die angezeigt oder heruntergeladen werden können)
    - `timestamp`, `status` (first, step, last)
- **Logpanel**: Zeigt den Fortschritt und Status des Workflows an. Die Logs werden aus `/api/workflows/{workflowId}/logs` geladen und enthalten:
    - `message`: Logtext
    - `progress`: Fortschritt (0-100%)
    - `type`: info, warning, error
    - `agentName`, `timestamp`
- **Prompt-Eingabe**: Textfeld für Nutzereingaben, Datei-Upload-Bereich, Start/Send-Button, Stop-Button
- **Dateianhänge**: Hochgeladene Dateien werden im UI angezeigt und können entfernt werden. Die Metadaten kommen aus `/api/files/upload` und den Nachrichtenobjekten.
- **Statusanzeige**: Zeigt den aktuellen Workflow-Status (running, completed, failed, stopped) an, basierend auf `/api/workflows/{workflowId}/status`.
- **Polling-Mechanismus**: Das Frontend pollt periodisch die Status-, Log- und Nachrichtenendpunkte, um die UI aktuell zu halten. Neue Nachrichten und Logs werden automatisch ergänzt.
- **Fehler- und Abschlusszustände**: Bei Fehlern oder Abschluss werden entsprechende UI-Elemente (z.B. Retry, Reset, neue Eingabe) angezeigt.

**Datenfluss:**
- Nach Start eines Workflows werden alle relevanten Daten (Nachrichten, Logs, Status) regelmäßig vom Backend geladen und im UI aktualisiert.
- Die Zuordnung von Nachrichten, Logs und Dateien erfolgt über IDs und Statusfelder.
- Die UI ist so gestaltet, dass sie den aktuellen Stand des Workflows und alle relevanten Aktionen für den Nutzer transparent darstellt.

---

**Letzte Aktualisierung:** 2024-05-11