349 lines
13 KiB
Markdown
349 lines
13 KiB
Markdown
# 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](#overview)
|
|
2. [Customer Journey 1: Discovering and Browsing Prompts](#customer-journey-1-discovering-and-browsing-prompts)
|
|
3. [Customer Journey 2: Viewing Prompt Details](#customer-journey-2-viewing-prompt-details)
|
|
4. [Customer Journey 3: Creating New Prompts](#customer-journey-3-creating-new-prompts)
|
|
5. [Customer Journey 4: Editing Prompt Properties](#customer-journey-4-editing-prompt-properties)
|
|
6. [Customer Journey 5: Starting a Prompt Workflow](#customer-journey-5-starting-a-prompt-workflow)
|
|
7. [Customer Journey 6: Deleting Prompts](#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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
```
|
|
|