gateway/docs/frontend-documentation/prompt-page-customer-journeys.md

Prompt Routes Frontend Documentation

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

Table of Contents

1. Overview
2. Customer Journey 1: Discovering and Browsing Prompts
3. Customer Journey 2: Viewing Prompt Details
4. Customer Journey 3: Creating New Prompts
5. Customer Journey 4: Editing Prompt Properties
6. Customer Journey 5: Starting a Prompt Workflow
7. Customer Journey 6: Deleting Prompts

---

Overview

The prompt routes (/api/prompts) enable users to manage prompts within their mandate. These routes focus on prompt administration including creation, editing, 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
• Mandate-Scoped: Prompts are managed within the context of mandates

---

Customer Journey 1: Discovering and Browsing Prompts

User Goal

"I want to see all prompts in my mandate and find the one I'm looking for."

User Story

As a user, I want to browse prompts, search for specific prompts, filter by any field, sort them by different criteria, and quickly identify prompts by their name and content.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Navigate to /prompts
    Frontend->>Backend: GET /api/attributes/Prompt
    Backend-->>Frontend: Attribute definitions (fields, labels, types)
    Frontend->>Backend: GET /api/prompts/?pagination=...
    Backend-->>Frontend: Paginated prompts list
    Frontend->>Frontend: Generate table columns from attributes
    Frontend->>Frontend: Generate filter controls from attributes
    Frontend->>Frontend: Render prompts table + search + filters
    Frontend->>Frontend: Render action buttons in table (Start Prompt, Edit, Delete)
    Frontend-->>User: Display prompt list with search/filter UI + action buttons
    
    alt User performs general search
        User->>Frontend: Type in search box (e.g., "invoice")
        Frontend->>Frontend: Update search query
        Frontend->>Backend: GET /api/prompts/?pagination=...filters:{"search":"invoice"}
        Backend-->>Frontend: Filtered prompts list
        Frontend-->>User: Display matching prompts
    end
    
    alt User applies field filter
        User->>Frontend: Select filter field (e.g., "Name")
        Frontend->>Frontend: Show filter options from attribute metadata
        User->>Frontend: Select filter value (e.g., "Invoice")
        Frontend->>Frontend: Update filter parameters
        Frontend->>Backend: GET /api/prompts/?pagination=...filters:{"name":"Invoice"}
        Backend-->>Frontend: Filtered prompts list
        Frontend-->>User: Display filtered prompts
    end
    
    alt User combines search + filter + sort
        User->>Frontend: Apply search + filter + sort
        Frontend->>Frontend: Combine all parameters
        Frontend->>Backend: GET /api/prompts/?pagination=...filters:{"search":"invoice","name":"Invoice"}...sort:desc
        Backend-->>Frontend: Filtered, sorted prompts list
        Frontend-->>User: Display results
    end
    
    User->>Frontend: Click column header (e.g., "Name")
    Frontend->>Frontend: Update sort parameters
    Frontend->>Backend: GET /api/prompts/?pagination=...sort:desc
    Backend-->>Frontend: Sorted prompts list
    Frontend-->>User: Display sorted prompts
    
    User->>Frontend: Click prompt row
    Frontend->>Frontend: Navigate to /prompts/promptId
    Frontend-->>User: Show prompt detail page

---

Customer Journey 2: Viewing Prompt Details

User Goal

"I want to see everything about a specific prompt—its name and full content."

User Story

As a user, I want to open a prompt and see its complete information, including name, content, and mandate association.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click prompt from list
    Frontend->>Backend: GET /api/prompts/promptId
    Backend-->>Frontend: Prompt object
    
    Frontend->>Backend: GET /api/attributes/Prompt
    Backend-->>Frontend: Field definitions
    
    Frontend->>Frontend: Generate UI from metadata
    Frontend->>Frontend: Render prompt info section
    Frontend->>Frontend: Separate editable vs read-only fields
    Frontend-->>User: Display complete prompt view
    
    alt User has editable fields and permission
        Frontend->>Frontend: Show "Edit Prompt" button
    end
    
    alt User has permission
        Frontend->>Frontend: Show "Delete Prompt" button
    end

---

Customer Journey 3: Creating New Prompts

User Goal

"I want to create new prompts for my mandate."

User Story

As a user, I want to create a new prompt by filling out a form with its name and content. The form should validate all required fields and show clear error messages.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Create Prompt" button
    Frontend->>Frontend: Navigate to /prompts/create
    
    Frontend->>Backend: GET /api/attributes/Prompt
    Backend-->>Frontend: Field definitions (editable fields)
    
    Frontend->>Frontend: Filter editable fields
    Frontend->>Frontend: Generate form from attributes
    Frontend-->>User: Display create prompt form
    
    User->>Frontend: Fill in form fields
    User->>Frontend: Click "Create"
    
    Frontend->>Frontend: Validate form (required fields, types)
    alt Validation fails
        Frontend-->>User: Show validation errors
    else Validation passes
        Frontend->>Frontend: Optimistic update: Show loading state, prepare UI for new prompt
        Frontend->>Backend: POST /api/prompts + form data
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend->>Frontend: Revert optimistic update: Show form with error
            Frontend-->>User: Show permission error
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request + error details
            Frontend->>Frontend: Revert optimistic update: Show form with errors
            Frontend-->>User: Show backend validation errors
        else Success (200)
            Backend-->>Frontend: Created prompt object
            Frontend->>Frontend: Keep optimistic update
            Frontend->>Backend: GET /api/prompts/promptId (refetch)
            Backend-->>Frontend: Created prompt object
            Frontend->>Frontend: Update UI with fresh data
            Frontend->>Frontend: Navigate to prompt detail page
            Frontend-->>User: Show created prompt
        end
    end

---

Customer Journey 4: Editing Prompt Properties

User Goal

"I want to change prompt settings like its name or content."

User Story

As a user, I want to edit a prompt's properties through a form that only shows fields I'm allowed to edit, with validation and clear error messages.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Edit" button
    Frontend->>Frontend: Navigate to /prompts/id/edit
    
    Frontend->>Backend: GET /api/prompts/promptId
    Backend-->>Frontend: Current prompt data
    
    Frontend->>Backend: GET /api/attributes/Prompt
    Backend-->>Frontend: Field definitions (editable fields)
    
    Frontend->>Frontend: Filter editable fields
    Frontend->>Frontend: Generate form from attributes
    Frontend->>Frontend: Pre-populate form with prompt data
    Frontend-->>User: Display edit form
    
    User->>Frontend: Modify form fields
    User->>Frontend: Click "Save"
    
    Frontend->>Frontend: Validate form (required fields, types)
    alt Validation fails
        Frontend-->>User: Show validation errors
    else Validation passes
        Frontend->>Frontend: Optimistic update: Apply changes to UI immediately
        Frontend->>Backend: PUT /api/prompts/promptId + form data
        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: Updated prompt
            Frontend->>Frontend: Keep optimistic update (or refresh from response)
            Frontend->>Backend: GET /api/prompts/promptId (refetch)
            Backend-->>Frontend: Updated prompt object
            Frontend->>Frontend: Update UI with fresh data
            Frontend->>Frontend: Navigate to detail page
            Frontend-->>User: Show updated prompt
        end
    end

---

Customer Journey 5: Starting a Prompt Workflow

User Goal

"I want to start a workflow using a prompt I've created."

User Story

As a user, I want to start a workflow in the chat playground using a prompt's content, so I can execute the prompt and see the results.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Start Prompt" button in table
    Frontend->>Backend: GET /api/prompts/promptId
    Backend-->>Frontend: Prompt object (name, content)
    
    Frontend->>Frontend: Navigate to /chat-playground
    Frontend->>Frontend: Pre-fill prompt content in chat input
    Frontend->>Frontend: Show prompt name as context
    Frontend-->>User: Display chat playground with prompt loaded
    
    User->>Frontend: Optionally modify prompt or add files
    User->>Frontend: Click "Start" or "Send" button
    
    Frontend->>Frontend: Validate user input
    alt Validation fails
        Frontend-->>User: Show validation errors
    else Validation passes
        Frontend->>Backend: POST /api/chat/playground/start?workflowMode=Dynamic<br/>Body: {prompt: promptContent, listFileId: [...], userLanguage: "en"}
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend-->>User: Show permission error
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request + error details
            Frontend-->>User: Show backend validation errors
        else Success (200)
            Backend-->>Frontend: Created workflow object
            Frontend->>Frontend: Update chat playground UI with workflow
            Frontend-->>User: Show workflow started, display messages/logs
        end
    end

---

Customer Journey 6: Deleting Prompts

User Goal

"I want to delete prompts that are no longer needed."

User Story

As a user, I want to delete prompts with a clear confirmation to prevent accidental deletion.

User Story Flow

sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Delete" button
    Frontend->>Backend: GET /api/prompts/promptId
    Backend-->>Frontend: Prompt data (for name)
    Frontend->>Frontend: Show confirmation dialog<br/>"Delete 'Prompt Name'?"
    User->>Frontend: Cancel deletion
    Frontend-->>User: Dialog closed, no action
    
    User->>Frontend: Click "Delete" button again
    Frontend->>Backend: GET /api/prompts/promptId
    Backend-->>Frontend: Prompt data
    Frontend->>Frontend: Show confirmation dialog
    User->>Frontend: Confirm deletion
    Frontend->>Frontend: Optimistic update: Remove prompt from UI immediately
    Frontend->>Backend: DELETE /api/prompts/promptId
    
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend->>Frontend: Revert optimistic update: Restore prompt in UI
        Frontend-->>User: Show permission error
    else Not found (404)
        Backend-->>Frontend: 404 Not Found
        Frontend->>Frontend: Revert optimistic update: Restore prompt in UI
        Frontend-->>User: Show not found error
    else Success (200)
        Backend-->>Frontend: Success response
        Frontend->>Frontend: Keep optimistic update (prompt already removed)
        Frontend->>Frontend: Show success message
        Frontend->>Frontend: Navigate to /prompts (if on detail page)
        Frontend-->>User: Display prompt list (without deleted prompt)
    end