# State Machine Documentation for Frontend Chat Workflow

## Overview

Die Chat-Workflow-Frontend-Logik implementiert eine State Machine, die Benutzerinteraktionen, Datei-Uploads und die Kommunikation mit dem Backend orchestriert. Die State Machine steuert die UI, das Polling und die Statusübergänge und sorgt für eine robuste, reaktive Multi-Agent-Chat-Erfahrung.

## Core Objects

### Frontend Workflow State Object
```json
{
  "status": "string", // null, "running", "completed", "failed", "stopped"
  "workflowId": "string", // null oder eindeutige Workflow-ID
  "logs": [], // Log-Einträge
  "chatMessages": [], // Chat-Nachrichten
  "lastPolledLogId": "string", // ID des letzten abgeholten Logs
  "lastPolledMessageId": "string", // ID der letzten abgeholten Nachricht
  "dataStats": {
    "bytesSent": int,
    "bytesReceived": int,
    "tokensUsed": float,
    "processingTime": float
  },
  "pollFailCount": int, // Zähler für Polling-Fehler
  "pollActive": boolean, // Steuert, ob Polling aktiv ist
  "sessionId": "string" // Session-Isolation
}
```

### User Input State Object
```json
{
  "promptText": "string", // Aktueller Benutzereingabetext
  "additionalFiles": [ /* File-Objekte, nicht nur IDs! */ ],
  "domElements": {}, // Referenzen auf UI-DOM-Elemente
  "sessionId": "string"
}
```

### Log Entry Object
```json
{
  "id": "log_timestamp",
  "message": "string",
  "progress": int, // Optional, 0-100
  "type": "string", // info, warning, error
  "timestamp": "ISO-datetime",
  "agentName": "string", // Name des Agents
  "waiting": boolean, // Zeigt Wartedots-Animation
  "highlighted": boolean // Für visuelles Highlighting
}
```

### Chat Message Object
```json
{
  "id": "msg_type_timestamp",
  "role": "string", // user, assistant  
  "agentName": "string",
  "content": "string",
  "documents": [], // Liste von File-Objekten
  "timestamp": "ISO-datetime",
  "status": "string" // first, step, last
}
```

### File Object
```json
{
  "id": "number|string", // numerisch oder UUID
  "name": "fileName.ext",
  "size": int,
  "mimeType": "string", // MIME-Type (z.B. application/pdf)
  "base64Encoded": boolean, // optional
  "content": "string", // optional, für Preview
  "isExtracted": boolean // optional, Parsing-Status
}
```

## State Machine Workflow

### 1. Initial State
- **State**: `null` (Kein Workflow aktiv)
- **UI**: Leerer Chat, Eingabefeld aktiv, Start-Button aktiv, Stop-Button ausgeblendet, File-Upload aktiv, leeres Logpanel
- **Aktionen**: Prompt eingeben, Dateien anhängen, Start klicken
- **API**: Keine

### 2. Prompt Preparation
- **State**: `null` (Übergang zu `running`)
- **Trigger**: Eingabe im Promptfeld, Datei-Upload, Prompt-Auswahl
- **Prozess**: Dateien werden via `api.uploadFile` hochgeladen, erscheinen als File-Objekte in `userInputState.additionalFiles`
- **API**: `POST /api/files/upload` pro Datei

### 3. Workflow Initialization
- **State**: `running`
- **Trigger**: Start-Button oder Enter
- **Prozess**: Validierung, UI-Ladezustand, Prompt und Files an Backend, Workflow-ID empfangen
- **State-Änderungen**: `status` → `running`, `workflowId` gesetzt, Files und Prompt zurückgesetzt
- **API**: `POST /api/workflows/start` (bzw. mit ID für Fortsetzung)

### 4. Polling for Updates
- **State**: `running`
- **Prozess**: Polling für Status, Logs, Messages (nur wenn `pollActive` true)
- **Polling-Details**:
  - Status: alle 2000ms
  - Logs: alle 1000ms
  - Messages: alle 1000ms
  - Polling stoppt sofort bei `failed` oder `stopped`, bei `completed` erst nach Message mit `status: last`
  - Exponentielles Backoff bei Fehlern (`pollFailCount`)
- **API**: `GET /api/workflows/{workflowId}/status|logs|messages`

### 5. Workflow Running
- **State**: `running`
- **Prozess**: Backend verarbeitet, Frontend pollt, Logs und Messages werden angezeigt
- **UI**: Stop-Button sichtbar, Eingabe gesperrt, Logpanel zeigt Fortschritt, Chat zeigt Agenten-Antworten
- **Aktionen**: Stop möglich, File-Previews, Downloads
- **API**: wie oben, Stop: `POST /api/workflows/{workflowId}/stop`

### 6. Workflow Completion
- **State**: `completed`
- **Trigger**: Backend gibt Status "completed" oder Message mit `status: last`
- **Prozess**: Finalmessage, Eingabe wieder aktiv, Polling stoppt
- **API**: keine bis neue Eingabe

### 7. Workflow Failure
- **State**: `failed`
- **Trigger**: Backend gibt Status "failed"
- **Prozess**: Fehlermeldung, Retry möglich, Polling stoppt
- **API**: keine bis Retry

### 8. Workflow Stopped
- **State**: `stopped`
- **Trigger**: Stop-Button oder Backend gibt "stopped"
- **Prozess**: Verarbeitung gestoppt, Polling stoppt
- **API**: keine bis Fortsetzung oder Reset

### 9. User Input Requested
- **State**: variiert
- **Trigger**: Message mit `status: last` oder Workflow nicht mehr `running`
- **Prozess**: Log "Waiting for user input", Eingabe aktiv
- **API**: keine bis neue Eingabe

### 10. Continuation Preparation
- **State**: `completed`, `failed`, `stopped` (Übergang zu `running`)
- **Trigger**: Neue Eingabe nach vorherigem Zyklus
- **Prozess**: Fortsetzung mit bestehender Workflow-ID, Files können ergänzt werden
- **API**: wie Prompt Preparation

### 11. Workflow Resumption
- **State**: `running`
- **Trigger**: Fortsetzung nach Stop/Fehler/Abschluss
- **Prozess**: Neue Eingabe mit bestehender Workflow-ID, Polling startet erneut
- **API**: `POST /api/workflows/start?id={workflowId}`

### 12. Workflow Reset
- **State**: `null`
- **Trigger**: Reset-Button
- **Prozess**: Alle State-Daten gelöscht, UI zurückgesetzt
- **API**: Optional `DELETE /api/workflows/{workflowId}`

## API Interaction Details

### Polling Implementation
- Polling läuft nur, wenn `pollActive` true ist
- Nach Statuswechsel zu `failed` oder `stopped` wird Polling sofort gestoppt
- Bei `completed` läuft Polling weiter, bis eine Message mit `status: last` kommt
- Exponentielles Backoff bei Fehlern (`pollFailCount`)
- Events wie `workflowStatusChanged`, `chatMessagesUpdated`, etc. synchronisieren die UI

### API Endpoints Used

| Frontend Function         | Backend Endpoint                                 | Parameters                        | Description                                 |
|--------------------------|--------------------------------------------------|------------------------------------|---------------------------------------------|
| `startWorkflow()`        | `POST /api/workflows/start`                      | `{ prompt: string, fileIds: [] }`  | Startet neuen Workflow                      |
| `continueWorkflow()`     | `POST /api/workflows/start?id={workflowId}`      | `{ prompt: string, fileIds: [] }`  | Setzt bestehenden Workflow fort             |
| `pollWorkflowStatus()`   | `GET /api/workflows/{workflowId}/status`         | None                               | Holt aktuellen Workflow-Status              |
| `pollWorkflowLogs()`     | `GET /api/workflows/{workflowId}/logs?id={lastLogId}` | Optional log ID              | Holt neue Logs                              |
| `pollWorkflowMessages()` | `GET /api/workflows/{workflowId}/messages?id={lastMessageId}` | Optional message ID         | Holt neue Nachrichten                       |
| `stopWorkflow()`         | `POST /api/workflows/{workflowId}/stop`          | None                               | Stoppt laufenden Workflow                   |
| `resetWorkflow()`        | `DELETE /api/workflows/{workflowId}`             | None                               | Löscht Workflow-Ressourcen                  |
| `uploadFile()`           | `POST /api/files/upload`                         | FormData mit Datei                 | Lädt Datei hoch und gibt File-Objekt zurück |
| `deleteMessage()`        | `DELETE /api/workflows/{workflowId}/messages/{messageId}` | None                        | Entfernt Nachricht aus Workflow             |
| `removeFileFromMessage()`| `DELETE /api/workflows/{workflowId}/messages/{messageId}/files/{fileId}` | None                | Entfernt Datei aus Nachricht                |

## Special Features

### File Handling
- File-Uploads liefern vollständige File-Objekte (siehe oben)
- File-Previews, Download, Copy werden unterstützt
- Jedes File kann einzeln entfernt werden

### Chat Message Rendering
- User- und Agenten-Nachrichten, Markdown, File-Attachments, Zeitstempel, Collapsible Content

### Log Panel Features
- Info/Warning/Error, Progress, Waiting-Animation, Highlighting, Collapsible Details, Timestamps

### Waiting States
- Dots-Animation in Logs, Spinner im Send-Button, Progress in Agent-Logs
- State-Management über `waiting`-Flag, `waitingDotsInterval`, `setLoadingState()`

## State Transitions

```
[null] → [running]               // Initial prompt submission
[running] → [running]            // Ongoing polling updates
[running] → [completed]          // Workflow completes successfully
[running] → [stopped]            // User manually stops workflow
[running] → [failed]             // Error occurs during workflow
[completed] → [running]          // User continues workflow with new input
[stopped] → [running]            // User continues after manual stop
[failed] → [running]             // User retries workflow despite error
[any] → [null]                   // User resets workflow
```

## Error Handling

### Client-side Errors
- Retry-Mechanismus im Polling (`pollFailCount`)
- Exponentielles Backoff
- Fehlerlogs und Toasts

### Backend Communication Errors
- Fehlerlogging, User-Feedback, Retry-Option, Toasts

### Data Inconsistencies
- Fallbacks bei ID-Matching, File-Referenzen, Content Extraction

## Implementation Notes

1. **Module Structure:**
   - `workflow.js`: Main initialization and coordination
   - `workflowCoordination.js`: State management
   - `workflowData.js`: Backend communication
   - `workflowUi.js`: UI rendering
   - `workflowUtils.js`: Helper functions

2. **Key Functions:**
   - `initWorkflowModule()`: Entry point for initialization
   - `updateWorkflowStatus()`: Core state transition function
   - `pollWorkflowStatus()`: Main update loop
   - `sendUserResponse()`: Handles user input submission
   - `renderLogs()` und `renderChatMessages()`: UI update functions

3. **Performance Optimizations:**
   - Selektive DOM-Updates
   - Scroll-Position-Preservation
   - Datenmengen-Schätzung für Statistik
   - Bedingtes Re-Rendering