Ida Dittrich 8970761bb8 extended PEK routes and included swisstopo connector

2025-12-15 07:21:17 +01:00

27 KiB

Raw Blame History

Chat Playground and Workflow Live Tracking Frontend Documentation

This document describes customer journeys for managing chat playground workflows and live tracking workflow execution through the frontend, focusing on how users interact with workflow management and how the backend routes support these experiences. All UI components are dynamically generated from backend metadata—no hardcoding required.

Overview
Customer Journey 1: Starting a New Workflow
Customer Journey 2: Continuing an Existing Workflow
Customer Journey 3: Live Tracking Workflow Progress
Customer Journey 4: Stopping a Running Workflow
Customer Journey 5: Deleting Context from a Workflow

Overview

The chat playground routes (/api/chat/playground) and workflow routes (/api/workflows) enable users to create, manage, and track AI-powered workflows that process user requests through task planning and action execution. These routes support workflow lifecycle management including creation, live tracking, modification, and deletion.

Key Principles:

User-Centric: Documentation organized around what users want to accomplish
Backend-Driven: All forms, tables, and UI components generated from backend metadata
No Hardcoding: Field definitions, labels, validation rules, and options come from the backend
Permission-Aware: Backend enforces permissions; frontend handles gracefully
User-Scoped: Users can only see and manage their own workflows
Real-Time Updates: Polling-based live tracking for workflow progress

Customer Journey 1: Starting a New Workflow

User Goal

"I want to start a new AI workflow to process my request."

User Story

As a user, I want to start a new workflow by optionally selecting a saved prompt template, providing or editing my input prompt, choosing a workflow mode (Actionplan for traditional task planning, Dynamic for iterative processing, or Template for template-based processing), optionally enabling data neutralization for privacy compliance, and optionally attaching files, so the system can begin processing my request in the appropriate mode with sensitive data protected if needed.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Navigate to chat playground
    Frontend->>Backend: GET /api/attributes/ChatWorkflow
    Backend-->>Frontend: Attribute definitions (fields, labels, types)
    Frontend->>Backend: GET /api/attributes/UserInputRequest
    Backend-->>Frontend: Input request field definitions
    Frontend->>Frontend: Generate input form from attributes
    Frontend->>Backend: GET /api/prompts
    Backend-->>Frontend: Paginated prompts list
    Frontend-->>User: Display chat input form with mode selector<br/>(Actionplan, Dynamic, Template)<br/>+ prompt dropdown selector
    
    alt User optionally selects a prompt
        User->>Frontend: Click prompt dropdown
        Frontend->>Frontend: Display available prompts list<br/>(from cached prompts data)
        User->>Frontend: Select prompt from dropdown
        Frontend->>Backend: GET /api/prompts/promptId
        Backend-->>Frontend: Selected prompt details<br/>(name, content)
        Frontend->>Frontend: Pre-fill prompt text field with prompt content
        Frontend->>Frontend: Show selected prompt name
        Frontend-->>User: Display prompt text pre-filled<br/>(user can still edit)
    end
    
    User->>Frontend: Enter or edit prompt text
    
    alt User selects workflow mode
        alt User selects "Actionplan" mode
            User->>Frontend: Click "Actionplan" mode option
            Frontend->>Frontend: Show mode description/help text<br/>(traditional task planning)
            Frontend->>Frontend: Set workflowMode to "Actionplan"
            Frontend-->>User: Display selected mode indicator
        else User selects "Dynamic" mode
            User->>Frontend: Click "Dynamic" mode option
            Frontend->>Frontend: Show mode description/help text<br/>(iterative dynamic-style processing)
            Frontend->>Frontend: Set workflowMode to "Dynamic"
            Frontend-->>User: Display selected mode indicator
        else User selects "Template" mode
            User->>Frontend: Click "Template" mode option
            Frontend->>Frontend: Show mode description/help text<br/>(template-based processing)
            Frontend->>Frontend: Set workflowMode to "Template"
            Frontend-->>User: Display selected mode indicator
        end
    end
    
    alt User optionally enables neutralization
        User->>Frontend: Click "Enable Neutralization" toggle
        Frontend->>Backend: GET /api/neutralization/config
        Backend-->>Frontend: Neutralization config (enabled status)
        alt Config exists and enabled
            Frontend->>Frontend: Mark neutralization as enabled for workflow
            Frontend-->>User: Show neutralization enabled indicator<br/>(uses existing config)
        else Config disabled or not found
            Frontend->>Frontend: Mark neutralization as disabled
            Frontend-->>User: Show neutralization disabled<br/>(user can configure on settings page)
        end
    end
    
    alt User optionally attaches files
        alt User drags and drops files
            User->>Frontend: Drag file(s) over drop zone
            Frontend->>Frontend: Show visual feedback<br/>(highlight drop zone, border, overlay)
            Frontend-->>User: Display drop zone active state
            User->>Frontend: Drop file(s) onto drop zone
            Frontend->>Frontend: Process dropped files
            Frontend->>Frontend: Show file preview with name and size
            Frontend->>Frontend: Optimistic update: Add file to attachment list
            Frontend->>Backend: POST /api/files/upload<br/>+ multipart/form-data (file)
            alt Permission denied (403)
                Backend-->>Frontend: 403 Forbidden
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show permission error
            else File too large (413)
                Backend-->>Frontend: 413 Request Entity Too Large
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show file size error
            else Success (201)
                Backend-->>Frontend: FileItem object + duplicate info
                Frontend->>Frontend: Keep optimistic update
                Frontend->>Frontend: Store fileId for later use
                Frontend-->>User: Show file attached successfully
            end
        else User uploads new file via button
            User->>Frontend: Click "Attach File" or "Upload File" button
            Frontend->>Frontend: Open file picker dialog
            User->>Frontend: Select file(s) from device
            Frontend->>Frontend: Show file preview with name and size
            Frontend->>Frontend: Optimistic update: Add file to attachment list
            Frontend->>Backend: POST /api/files/upload<br/>+ multipart/form-data (file)
            alt Permission denied (403)
                Backend-->>Frontend: 403 Forbidden
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show permission error
            else File too large (413)
                Backend-->>Frontend: 413 Request Entity Too Large
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show file size error
            else Success (201)
                Backend-->>Frontend: FileItem object + duplicate info
                Frontend->>Frontend: Keep optimistic update
                Frontend->>Frontend: Store fileId for later use
                Frontend-->>User: Show file attached successfully
            end
        else User selects existing file
            User->>Frontend: Click "Browse Files" or "Select File" button
            Frontend->>Backend: GET /api/files/list
            Backend-->>Frontend: Paginated files list
            Frontend->>Frontend: Display file browser/selector
            Frontend-->>User: Show available files
            User->>Frontend: Select file(s) from list
            Frontend->>Frontend: Add fileId(s) to attachment list
            Frontend-->>User: Show selected files in attachment list
        end
    end
    
    User->>Frontend: Click "Start Workflow" button
    
    Frontend->>Frontend: Validate form (required fields, types, workflowMode)
    alt Validation fails (missing workflowMode or prompt)
        Frontend-->>User: Show validation errors<br/>(e.g., "Workflow mode is required")
    else Validation passes
        Frontend->>Frontend: Build UserInputRequest with listFileId array (if files attached)
        alt Neutralization enabled
            Frontend->>Frontend: Neutralization will be applied automatically<br/>by backend during workflow processing
        end
        Frontend->>Frontend: Optimistic update: Show loading state, create workflow placeholder
        Frontend->>Backend: POST /api/chat/playground/start<br/>+ workflowMode query param (Actionplan/Dynamic/Template)<br/>+ UserInputRequest body<br/>(includes listFileId if files attached)
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show permission error
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request + error details
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show backend validation errors
        else Success (200)
            Backend-->>Frontend: Created ChatWorkflow (status: "running")<br/>with files attached (if any)<br/>(neutralized if neutralization enabled)
            Frontend->>Frontend: Keep optimistic update
            Frontend->>Frontend: Navigate to workflow view
            Frontend->>Frontend: Start polling for updates
            alt Neutralization enabled
                Frontend->>Frontend: Show neutralization indicator in workflow view
                Frontend->>Frontend: Option to resolve text back to original when viewing
            end
            Frontend-->>User: Display workflow with live tracking<br/>(files visible if attached, neutralized if enabled)
        end
    end

Customer Journey 2: Continuing an Existing Workflow

User Goal

"I want to continue a workflow I started earlier by selecting it from a list and adding more input."

User Story

As a user, I want to select a previous workflow from a dropdown on the chat interface page and continue it by providing additional input, so the system can process my new request in the context of the previous conversation.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Navigate to chat playground
    Frontend->>Backend: GET /api/attributes/ChatWorkflow
    Backend-->>Frontend: Attribute definitions (fields, labels, types)
    Frontend->>Backend: GET /api/attributes/UserInputRequest
    Backend-->>Frontend: Input request field definitions
    Frontend->>Backend: GET /api/workflows/
    Backend-->>Frontend: Paginated workflows list
    Frontend->>Backend: GET /api/prompts
    Backend-->>Frontend: Paginated prompts list
    Frontend->>Frontend: Generate input form from attributes
    Frontend-->>User: Display chat input form with<br/>workflow dropdown selector<br/>+ mode selector + prompt dropdown
    
    alt User selects previous workflow from dropdown
        User->>Frontend: Click workflow dropdown
        Frontend->>Frontend: Display available workflows list<br/>(from cached workflows data)
        User->>Frontend: Select workflow from dropdown
        Frontend->>Backend: GET /api/workflows/workflowId
        Backend-->>Frontend: Selected workflow data<br/>(status, messages, workflowMode, etc.)
        Frontend->>Frontend: Load workflow history
        Frontend->>Frontend: Display previous messages in chat view
        Frontend->>Frontend: Set workflowMode from selected workflow
        Frontend->>Frontend: Show selected workflow name/ID
        Frontend-->>User: Display workflow context<br/>(previous messages visible,<br/>workflow mode pre-selected)
    end
    
    alt User optionally selects a prompt
        User->>Frontend: Click prompt dropdown
        Frontend->>Frontend: Display available prompts list<br/>(from cached prompts data)
        User->>Frontend: Select prompt from dropdown
        Frontend->>Backend: GET /api/prompts/promptId
        Backend-->>Frontend: Selected prompt details<br/>(name, content)
        Frontend->>Frontend: Pre-fill prompt text field with prompt content
        Frontend->>Frontend: Show selected prompt name
        Frontend-->>User: Display prompt text pre-filled<br/>(user can still edit)
    end
    
    User->>Frontend: Enter or edit prompt text
    
    alt User optionally enables/disables neutralization
        User->>Frontend: Click "Enable Neutralization" toggle
        Frontend->>Backend: GET /api/neutralization/config
        Backend-->>Frontend: Neutralization config (enabled status)
        alt Config exists and enabled
            Frontend->>Frontend: Mark neutralization as enabled for workflow
            Frontend-->>User: Show neutralization enabled indicator<br/>(uses existing config)
        else Config disabled or not found
            Frontend->>Frontend: Mark neutralization as disabled
            Frontend-->>User: Show neutralization disabled<br/>(user can configure on settings page)
        end
    end
    
    alt User optionally attaches files
        alt User drags and drops files
            User->>Frontend: Drag file(s) over drop zone
            Frontend->>Frontend: Show visual feedback<br/>(highlight drop zone, border, overlay)
            Frontend-->>User: Display drop zone active state
            User->>Frontend: Drop file(s) onto drop zone
            Frontend->>Frontend: Process dropped files
            Frontend->>Frontend: Show file preview with name and size
            Frontend->>Frontend: Optimistic update: Add file to attachment list
            Frontend->>Backend: POST /api/files/upload<br/>+ multipart/form-data (file)<br/>+ workflowId (optional)
            alt Permission denied (403)
                Backend-->>Frontend: 403 Forbidden
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show permission error
            else File too large (413)
                Backend-->>Frontend: 413 Request Entity Too Large
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show file size error
            else Success (201)
                Backend-->>Frontend: FileItem object + duplicate info
                Frontend->>Frontend: Keep optimistic update
                Frontend->>Frontend: Store fileId for later use
                Frontend-->>User: Show file attached successfully
            end
        else User uploads new file via button
            User->>Frontend: Click "Attach File" or "Upload File" button
            Frontend->>Frontend: Open file picker dialog
            User->>Frontend: Select file(s) from device
            Frontend->>Frontend: Show file preview with name and size
            Frontend->>Frontend: Optimistic update: Add file to attachment list
            Frontend->>Backend: POST /api/files/upload<br/>+ multipart/form-data (file)<br/>+ workflowId (optional)
            alt Permission denied (403)
                Backend-->>Frontend: 403 Forbidden
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show permission error
            else File too large (413)
                Backend-->>Frontend: 413 Request Entity Too Large
                Frontend->>Frontend: Revert optimistic update: Remove file from list
                Frontend-->>User: Show file size error
            else Success (201)
                Backend-->>Frontend: FileItem object + duplicate info
                Frontend->>Frontend: Keep optimistic update
                Frontend->>Frontend: Store fileId for later use
                Frontend-->>User: Show file attached successfully
            end
        else User selects existing file
            User->>Frontend: Click "Browse Files" or "Select File" button
            Frontend->>Backend: GET /api/files/list
            Backend-->>Frontend: Paginated files list
            Frontend->>Frontend: Display file browser/selector
            Frontend-->>User: Show available files
            User->>Frontend: Select file(s) from list
            Frontend->>Frontend: Add fileId(s) to attachment list
            Frontend-->>User: Show selected files in attachment list
        end
    end
    
    User->>Frontend: Click "Continue" or "Send" button
    
    Frontend->>Frontend: Validate form (required fields, workflowMode)
    alt Validation fails (missing workflowMode or prompt)
        Frontend-->>User: Show validation errors<br/>(e.g., "Workflow mode is required")
    else Validation passes
        Frontend->>Frontend: Build UserInputRequest with listFileId array (if files attached)
        alt Neutralization enabled
            Frontend->>Frontend: Neutralization will be applied automatically<br/>by backend during workflow processing
        end
        Frontend->>Frontend: Optimistic update: Add user message to UI
        Frontend->>Backend: POST /api/chat/playground/start<br/>+ workflowId query param (from selected workflow)<br/>+ workflowMode query param (from selected workflow)<br/>+ UserInputRequest body<br/>(includes listFileId if files attached)
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show permission error
        else Workflow not found (404)
            Backend-->>Frontend: 404 Not Found
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show not found error
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request + error details
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show backend validation errors
        else Success (200)
            Backend-->>Frontend: Updated ChatWorkflow (status: "running")<br/>with new files attached (if any)<br/>(neutralized if neutralization enabled)
            Frontend->>Frontend: Keep optimistic update
            Frontend->>Frontend: Navigate to workflow view or update current view
            Frontend->>Frontend: Start/continue polling for updates
            alt Neutralization enabled
                Frontend->>Frontend: Show neutralization indicator in workflow view
                Frontend->>Frontend: Option to resolve text back to original when viewing
            end
            Frontend-->>User: Display updated workflow with new input<br/>(files visible if attached, neutralized if enabled)
        end
    end

Customer Journey 3: Live Tracking Workflow Progress

User Goal

"I want to see real-time updates as my workflow processes my request."

User Story

As a user, I want to see live updates including new messages, execution logs, and statistics as my workflow processes, so I can monitor progress and understand what the system is doing.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: View active workflow
    Frontend->>Frontend: Start polling interval (e.g., every 2 seconds)
    
    loop Polling cycle
        Frontend->>Backend: GET /api/chat/playground/workflowId/chatData<br/>+ afterTimestamp query param (optional)
        alt Workflow not found (404)
            Backend-->>Frontend: 404 Not Found
            Frontend->>Frontend: Stop polling
            Frontend-->>User: Show error, navigate away
        else Success (200)
            Backend-->>Frontend: Unified chat data<br/>{messages: [], logs: [], stats: []}<br/>(chronologically ordered by _createdAt)
            Frontend->>Frontend: Compare with existing data
            alt New data available
                Frontend->>Frontend: Append new messages to chat view
                Frontend->>Frontend: Append new logs to log panel
                Frontend->>Frontend: Update statistics display
                Frontend->>Frontend: Update workflow status indicator
                Frontend->>Frontend: Scroll to latest content (if auto-scroll enabled)
                Frontend-->>User: Display new messages, logs, stats
            else No new data
                Frontend->>Frontend: Continue polling silently
            end
            
            alt Workflow status is "completed" or "stopped" or "failed"
                Frontend->>Frontend: Stop polling
                Frontend->>Frontend: Show final status
                Frontend-->>User: Display completed workflow
            end
        end
    end
    
    alt User manually stops polling
        User->>Frontend: Navigate away or close tab
        Frontend->>Frontend: Stop polling interval
    end

Customer Journey 4: Stopping a Running Workflow

User Goal

"I want to stop a workflow that is currently running."

User Story

As a user, I want to stop a running workflow by clicking a stop button, so I can halt processing if I no longer need the results or if something is taking too long.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: View running workflow
    Frontend->>Frontend: Display "Stop" button
    User->>Frontend: Click "Stop" button
    
    Frontend->>Frontend: Show confirmation dialog<br/>"Stop this workflow?"
    alt User cancels
        User->>Frontend: Click "Cancel"
        Frontend->>Frontend: Close dialog
        Frontend-->>User: Dialog closed, workflow continues
    else User confirms
        User->>Frontend: Click "Confirm"
        Frontend->>Frontend: Optimistic update: Update status to "stopping"
        Frontend->>Backend: POST /api/chat/playground/workflowId/stop
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show permission error
        else Workflow not found (404)
            Backend-->>Frontend: 404 Not Found
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show not found error
        else Success (200)
            Backend-->>Frontend: Updated ChatWorkflow (status: "stopped")
            Frontend->>Frontend: Keep optimistic update
            Frontend->>Frontend: Stop polling for updates
            Frontend->>Backend: GET /api/workflows/workflowId (refetch)
            Backend-->>Frontend: Final workflow state
            Frontend->>Frontend: Update UI with stopped status
            Frontend-->>User: Show stopped workflow with final state
        end
    end

Customer Journey 5: Deleting Context from a Workflow

User Goal

"I want to remove messages or files from a workflow to clean up the context."

User Story

As a user, I want to delete individual messages or files attached to messages in a workflow, so I can remove unwanted context and keep the workflow focused on what's relevant.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    alt User deletes message from workflow
        User->>Frontend: View workflow with messages
        User->>Frontend: Click "Delete" button on message
        Frontend->>Frontend: Show confirmation dialog<br/>"Delete this message?<br/>This will remove it from the workflow context."
        alt User cancels
            User->>Frontend: Click "Cancel"
            Frontend->>Frontend: Close dialog
            Frontend-->>User: Dialog closed, message remains
        else User confirms
            User->>Frontend: Click "Confirm" or "Delete"
            Frontend->>Frontend: Optimistic update: Remove message from UI
            Frontend->>Backend: DELETE /api/workflows/workflowId/messages/messageId
            alt Permission denied (403)
                Backend-->>Frontend: 403 Forbidden
                Frontend->>Frontend: Revert optimistic update: Restore message
                Frontend-->>User: Show permission error
            else Message not found (404)
                Backend-->>Frontend: 404 Not Found
                Frontend->>Frontend: Revert optimistic update: Restore message
                Frontend-->>User: Show not found error
            else Success (200)
                Backend-->>Frontend: Success response<br/>{workflowId, messageId, message: "Message deleted successfully"}
                Frontend->>Frontend: Keep optimistic update
                Frontend->>Backend: GET /api/workflows/workflowId (refetch)
                Backend-->>Frontend: Updated workflow (messageIds updated)
                Frontend->>Frontend: Update UI with fresh workflow data
                Frontend-->>User: Show message removed from workflow
            end
        end
    end
    
    alt User deletes file from message
        User->>Frontend: View message with file attachments
        User->>Frontend: Click "Delete" button on file attachment
        Frontend->>Frontend: Show confirmation dialog<br/>"Delete this file?<br/>This will remove it from the message context."
        alt User cancels
            User->>Frontend: Click "Cancel"
            Frontend->>Frontend: Close dialog
            Frontend-->>User: Dialog closed, file remains
        else User confirms
            User->>Frontend: Click "Confirm" or "Delete"
            Frontend->>Frontend: Optimistic update: Remove file from UI
            Frontend->>Backend: DELETE /api/workflows/workflowId/messages/messageId/files/fileId
            alt Permission denied (403)
                Backend-->>Frontend: 403 Forbidden
                Frontend->>Frontend: Revert optimistic update: Restore file
                Frontend-->>User: Show permission error
            else File not found (404)
                Backend-->>Frontend: 404 Not Found
                Frontend->>Frontend: Revert optimistic update: Restore file
                Frontend-->>User: Show not found error
            else Success (200)
                Backend-->>Frontend: Success response<br/>{workflowId, messageId, fileId, message: "File reference deleted successfully"}
                Frontend->>Frontend: Keep optimistic update
                Frontend->>Backend: GET /api/workflows/workflowId/messages/messageId (refetch)
                Backend-->>Frontend: Updated message (files list updated)
                Frontend->>Frontend: Update UI with fresh message data
                Frontend-->>User: Show file removed from message
            end
        end
    end

27 KiB Raw Blame History

Chat Playground and Workflow Live Tracking Frontend Documentation

Table of Contents

Overview

Customer Journey 1: Starting a New Workflow

User Goal

User Story

User Story Flow

Customer Journey 2: Continuing an Existing Workflow

User Goal

User Story

User Story Flow

Customer Journey 3: Live Tracking Workflow Progress

User Goal

User Story

User Story Flow

Customer Journey 4: Stopping a Running Workflow

User Goal

User Story

User Story Flow

Customer Journey 5: Deleting Context from a Workflow

User Goal

User Story

User Story Flow

27 KiB

Raw Blame History