PowerOn/gateway
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gateway/docs/frontend-documentation/chat-playground-page-requirements.md

786 lines
31 KiB
Markdown
Raw Blame History

# Chat Playground Page Requirements
This document contains the complete frontend requirements for the chat playground page and workflow management components. All UI components are dynamically generated from backend metadata—no hardcoding required.
## Table of Contents
1. [Overview](#overview)
2. [Page Structure and Layout](#page-structure-and-layout)
3. [User Interactions and Functionality](#user-interactions-and-functionality)
4. [Backend Routes and API Integration](#backend-routes-and-api-integration)
5. [Field and Attribute Reference](#field-and-attribute-reference)
6. [Dynamic Rendering Guidelines](#dynamic-rendering-guidelines)
---
## Overview
The chat playground page enables users to create, manage, and track AI-powered workflows that process user requests through task planning and action execution. The frontend consists of a single page (`/chat-playground` or `/workflows/playground`) with different views/states:
- **Input View** - Start new workflows or continue existing ones with prompt input, mode selection, and file attachments
- **Workflow View** - Live tracking of workflow execution with messages, logs, and statistics
- **Workflow History View** - View completed workflows with full message history
All views use backend-driven UI generation, meaning field definitions, labels, validation rules, and UI structure come entirely from backend metadata through the `/api/attributes/ChatWorkflow` and `/api/attributes/UserInputRequest` endpoints. Views are managed through component state and routing within the same page, not as separate routes.
**Note:** Workflows are user-scoped. Users can only see and manage their own workflows. The backend enforces this security.
---
## Page Structure and Layout
### Chat Playground Page (`/chat-playground` or `/workflows/playground`)
The chat playground page uses different views/states to handle different user interactions. Views are managed through component state and routing within the same page component.
### Input View
**State:** `view === 'input'` or `selectedWorkflowId === null` (starting new workflow)
**What the user sees:**
- **Main Content Area:**
- Chat input form with the following components:
- **Workflow Dropdown** - Select previous workflow to continue (optional, shows "New Workflow" by default)
- **Prompt Dropdown** - Select saved prompt template (optional)
- **Prompt Text Input** - Multi-line text area for user input (required)
- **Workflow Mode Selector** - Radio buttons or tabs for Actionplan, Dynamic, or Template (required)
- **Neutralization Toggle** - Checkbox/toggle to enable/disable data neutralization (optional)
- **File Attachment Area** - Drop zone with drag-and-drop support, plus "Attach File" button and "Browse Files" button
- **Action Buttons:**
- "Start Workflow" button (when no workflow selected)
- "Continue Workflow" or "Send" button (when workflow selected)
- **File Attachment Display:**
- List of attached files with preview (name, size, type)
- Remove button for each attached file
- Visual feedback for drag-and-drop (highlight, border, overlay when dragging)
- **Workflow Context Display** (when workflow selected):
- Previous messages from selected workflow displayed in chat view
- Workflow status indicator
- Workflow mode pre-selected from selected workflow
### Workflow View
**State:** `view === 'workflow'` and `selectedWorkflowId !== null` (active workflow tracking)
**What the user sees:**
- **Main Content Area:**
- **Chat Interface:**
- Message history displayed chronologically
- User messages and assistant responses
- File attachments displayed as part of each message
- Each file attachment shows:
- File name, size, and type/icon
- Action buttons: "Show", "Download", "Delete"
- File preview (if applicable) when "Show" is clicked
- Auto-scroll to latest message (optional, user can disable)
- **Log Panel** (optional, can be toggled):
- Execution logs displayed chronologically
- Log level indicators (info, warning, error)
- Timestamps for each log entry
- **Statistics Panel** (optional, can be toggled):
- Performance metrics
- Task completion status
- Execution time
- **Workflow Status Indicator:**
- Current workflow status (running, completed, stopped, failed)
- Visual status badge with color coding
- Neutralization indicator (if enabled)
- **Action Buttons:**
- "Stop" button (when workflow is running)
- "Delete Message" button (on individual messages)
- **File Action Buttons** (on each file attachment in messages):
- "Show" button - Opens file preview/viewer
- "Download" button - Downloads file to user's device
- "Delete" button - Removes file from message (with confirmation)
- "Back to Input" button (return to input view)
- **Live Updates:**
- Real-time polling for new messages, logs, and statistics
- Visual indicators for new content
- Automatic UI updates without page refresh
---
## User Interactions and Functionality
### Starting a New Workflow
**Workflow Selection:**
- User sees workflow dropdown with "New Workflow" as default option
- Dropdown shows list of previous workflows (name, status, last activity)
- Selecting "New Workflow" clears any selected workflow context
- Selecting a previous workflow loads its context (messages, mode)
**Prompt Selection:**
- User can optionally select a saved prompt from dropdown
- Selecting a prompt pre-fills the prompt text field
- User can still edit the pre-filled text
- Prompt selection is optional
**Workflow Mode Selection:**
- User must select one of three modes:
- **Actionplan** - Traditional task planning (shows description on selection)
- **Dynamic** - Iterative dynamic-style processing (shows description on selection)
- **Template** - Template-based processing (shows description on selection)
- Mode selection is required before starting workflow
- Visual indicator shows selected mode
**Neutralization Toggle:**
- User can toggle neutralization on/off
- Frontend checks neutralization config status
- If config exists and enabled, neutralization is enabled for workflow
- If config disabled or not found, neutralization is disabled
- User can configure neutralization settings on separate settings page
- Toggle shows current state (enabled/disabled indicator)
**File Attachment:**
- **Drag and Drop:**
- User drags files over drop zone
- Visual feedback shown (highlight, border, overlay)
- User drops files onto drop zone
- Files processed and uploaded automatically
- File preview shown immediately
- **Button Upload:**
- User clicks "Attach File" or "Upload File" button
- File picker dialog opens
- User selects files from device
- Files uploaded and preview shown
- **Browse Existing Files:**
- User clicks "Browse Files" or "Select File" button
- File browser/selector opens with paginated file list
- User selects existing files
- Selected files added to attachment list
- **File Management:**
- Attached files shown in list with name, size, type
- Remove button for each file
- Multiple files can be attached
- Files validated before upload (size limits, type restrictions)
**Form Validation:**
- Required fields: prompt text, workflow mode
- Optional fields: prompt selection, neutralization, files
- Validation errors shown inline
- Form cannot be submitted until required fields are filled
**Workflow Submission:**
- User clicks "Start Workflow" button
- Form validates (required fields, types, workflowMode)
- If validation fails, show errors
- If validation passes:
- Build UserInputRequest with prompt, listFileId (if files attached), userLanguage
- Show loading state
- Submit to `/api/chat/playground/start` with workflowMode query param
- On success: Navigate to workflow view, start polling
- On error: Show error message, revert optimistic updates
### Continuing an Existing Workflow
**Workflow Selection:**
- User selects previous workflow from dropdown
- Frontend loads workflow data via `GET /api/workflows/workflowId`
- Previous messages displayed in chat view
- Workflow mode pre-selected from selected workflow
- Selected workflow name/ID shown
**Additional Input:**
- User can optionally select a prompt (pre-fills text)
- User enters or edits prompt text
- User can toggle neutralization
- User can attach files (same methods as starting new workflow)
**Workflow Continuation:**
- User clicks "Continue" or "Send" button
- Form validates (required fields)
- If validation passes:
- Build UserInputRequest with prompt, listFileId (if files attached)
- Show optimistic update (add user message to UI)
- Submit to `/api/chat/playground/start` with workflowId and workflowMode query params
- On success: Continue polling, update workflow view
- On error: Revert optimistic update, show error
### Live Tracking Workflow Progress
**Polling Mechanism:**
- Start polling when workflow view is active
- Poll interval: every 2 seconds (configurable)
- Poll endpoint: `GET /api/chat/playground/{workflowId}/chatData`
- Use `afterTimestamp` query param for selective data transfer
**Data Updates:**
- Compare new data with existing data
- If new data available:
- Append new messages to chat view
- Append new logs to log panel
- Update statistics display
- Update workflow status indicator
- Scroll to latest content (if auto-scroll enabled)
- If no new data, continue polling silently
**Polling Control:**
- Stop polling when workflow status is "completed", "stopped", or "failed"
- Stop polling when user navigates away
- Show final status when workflow completes
- Handle errors gracefully (404 stops polling, shows error)
**Visual Feedback:**
- Loading indicators during polling
- New content indicators
- Status change animations
- Progress indicators for long-running workflows
### Stopping a Running Workflow
**Stop Action:**
- User clicks "Stop" button (only visible when workflow is running)
- Confirmation dialog appears: "Stop this workflow?"
- User can cancel or confirm
**Stop Submission:**
- If user confirms:
- Show optimistic update (status to "stopping")
- Submit to `POST /api/chat/playground/{workflowId}/stop`
- On success: Stop polling, update UI with stopped status
- On error: Revert optimistic update, show error
### Viewing Files in Messages
**Show File:**
- User clicks "Show" button on file attachment in message
- Frontend fetches file data via `GET /api/files/{fileId}/download` or preview endpoint
- File preview/viewer opens (modal, sidebar, or inline)
- Preview supports different file types:
- Images → Display image viewer
- PDFs → Display PDF viewer
- Text files → Display text content
- Other types → Show file info or download prompt
- User can close preview to return to message view
**Download File:**
- User clicks "Download" button on file attachment in message
- Frontend triggers download via `GET /api/files/{fileId}/download`
- Browser automatically downloads file with proper filename
- File name properly encoded for Unicode characters
- Handle 403 (permission denied) and 404 (file not found) errors
### Deleting Context from a Workflow
**Delete Message:**
- User clicks "Delete" button on message
- Confirmation dialog: "Delete this message? This will remove it from the workflow context."
- If user confirms:
- Show optimistic update (remove message from UI)
- Submit to `DELETE /api/workflows/{workflowId}/messages/{messageId}`
- On success: Keep optimistic update, refresh workflow data
- On error: Revert optimistic update, show error
**Delete File from Message:**
- User clicks "Delete" button on file attachment in message
- Confirmation dialog: "Delete this file? This will remove it from the message context."
- If user confirms:
- Show optimistic update (remove file from UI)
- Submit to `DELETE /api/workflows/{workflowId}/messages/{messageId}/files/{fileId}`
- On success: Keep optimistic update, refresh message data
- On error: Revert optimistic update, show error
---
## Backend Routes and API Integration
### Complete Route Reference
All backend routes used by chat playground pages:
| Route | Method | Purpose | When Used | Access Control |
|-------|--------|---------|-----------|----------------|
| `/api/chat/playground/start` | POST | Start new workflow or continue existing | User clicks "Start Workflow" or "Continue" | Current user only |
| `/api/chat/playground/{workflowId}/stop` | POST | Stop running workflow | User clicks "Stop" button | Current user only |
| `/api/chat/playground/{workflowId}/chatData` | GET | Get unified chat data for polling | Live tracking (polling every 2 seconds) | Current user only |
| `/api/workflows/` | GET | Get all workflows for current user | Load workflow dropdown, initial page load | Current user only |
| `/api/workflows/{workflowId}` | GET | Get workflow by ID | User selects workflow from dropdown | Current user only |
| `/api/workflows/{workflowId}/messages/{messageId}` | DELETE | Delete message from workflow | User confirms message deletion | Current user only |
| `/api/workflows/{workflowId}/messages/{messageId}/files/{fileId}` | DELETE | Delete file from message | User confirms file deletion | Current user only |
| `/api/prompts` | GET | Get all prompts for current user | Load prompt dropdown | Current user only |
| `/api/prompts/{promptId}` | GET | Get prompt by ID | User selects prompt from dropdown | Current user only |
| `/api/files/upload` | POST | Upload new file | User drags/drops or clicks upload | Current user only |
| `/api/files/list` | GET | Get all files for current user | User clicks "Browse Files" | Current user only |
| `/api/files/{fileId}/download` | GET | Download file | User clicks "Download" button on file | Current user only |
| `/api/neutralization/config` | GET | Get neutralization config | User toggles neutralization | Current user only |
| `/api/attributes/ChatWorkflow` | GET | Get field definitions | Page load (once per page) | All authenticated users |
| `/api/attributes/UserInputRequest` | GET | Get field definitions | Page load (once per page) | All authenticated users |
### API Request Patterns
**Start Workflow Request:**
```
POST /api/chat/playground/start?workflowMode=Dynamic
Content-Type: application/json
Body: {
"prompt": "User prompt text here...",
"listFileId": ["fileId1", "fileId2"],
"userLanguage": "en"
}
```
- `workflowMode` query parameter is required: "Actionplan", "Dynamic", or "Template"
- `workflowId` query parameter is optional (for continuing existing workflow)
- `listFileId` array contains file IDs to attach (optional)
- `prompt` field contains user's prompt text (required)
- `userLanguage` should match user's preferred language
- Handle 403 (permission denied) and 400 (validation errors)
**Continue Workflow Request:**
```
POST /api/chat/playground/start?workflowId=workflow-id&workflowMode=Dynamic
Content-Type: application/json
Body: {
"prompt": "Additional prompt text...",
"listFileId": ["fileId1"],
"userLanguage": "en"
}
```
- `workflowId` query parameter is required (ID of workflow to continue)
- `workflowMode` query parameter is required (from selected workflow)
- Same body structure as start workflow
- Handle 403, 404 (workflow not found), and 400 errors
**Stop Workflow Request:**
```
POST /api/chat/playground/{workflowId}/stop
```
- No body required
- Returns updated ChatWorkflow with status "stopped"
- Handle 403 (permission denied) and 404 (workflow not found)
**Get Chat Data Request (Polling):**
```
GET /api/chat/playground/{workflowId}/chatData?afterTimestamp=1234567890.123
```
- `afterTimestamp` query parameter is optional (Unix timestamp for selective data transfer)
- Returns unified chat data: `{messages: [], logs: [], stats: []}`
- Data is chronologically ordered by `_createdAt` timestamp
- Handle 404 (workflow not found) - stop polling
**Get Workflows Request:**
```
GET /api/workflows/
```
- Returns paginated workflows list
- Can include pagination parameter: `?pagination={"page":1,"pageSize":10,"sort":[]}`
- Used to populate workflow dropdown
- Returns only current user's workflows
**Get Workflow Request:**
```
GET /api/workflows/{workflowId}
```
- Returns full workflow data including messages, logs, stats
- Used when user selects workflow from dropdown
- Handle 404 (workflow not found)
**Upload File Request:**
```
POST /api/files/upload
Content-Type: multipart/form-data
Body: {
file: <file data>,
workflowId: "optional-workflow-id" (optional)
}
```
- File sent as multipart/form-data
- `workflowId` is optional form field
- Handle 403 (permission denied), 413 (file too large), and 400 (validation errors)
- Response includes duplicate information
**Get Prompts Request:**
```
GET /api/prompts
```
- Returns paginated prompts list
- Used to populate prompt dropdown
- Returns only current user's prompts
**Get Prompt Request:**
```
GET /api/prompts/{promptId}
```
- Returns prompt details (name, content)
- Used when user selects prompt from dropdown
- Handle 404 (prompt not found)
**Get Neutralization Config Request:**
```
GET /api/neutralization/config
```
- Returns neutralization configuration (enabled status, settings)
- Used when user toggles neutralization
- Returns default config if none exists
**Delete Message Request:**
```
DELETE /api/workflows/{workflowId}/messages/{messageId}
```
- Deletes message from workflow
- Updates workflow's messageIds list
- Handle 403 (permission denied) and 404 (message not found)
**Download File Request:**
```
GET /api/files/{fileId}/download
```
- Returns file content with Content-Disposition header
- Browser automatically triggers download
- Filename properly encoded for Unicode characters
- Handle 403 (permission denied) and 404 (file not found)
**Delete File Request:**
```
DELETE /api/workflows/{workflowId}/messages/{messageId}/files/{fileId}
```
- Deletes file reference from message
- Handle 403 (permission denied) and 404 (file not found)
### Response Handling
**Start/Continue Workflow Response:**
```json
{
"id": "workflow-id",
"status": "running",
"workflowMode": "Dynamic",
"messages": [...],
"logs": [...],
"stats": [...],
...
}
```
- Returns ChatWorkflow object with status "running"
- Includes all workflow data
**Chat Data Response (Polling):**
```json
{
"messages": [
{
"id": "message-id",
"role": "user",
"content": "...",
"_createdAt": 1234567890.123,
...
}
],
"logs": [
{
"id": "log-id",
"level": "info",
"message": "...",
"_createdAt": 1234567890.124,
...
}
],
"stats": [
{
"id": "stat-id",
"metric": "...",
"value": 123,
"_createdAt": 1234567890.125,
...
}
]
}
```
- All data types in chronological order by `_createdAt`
- Empty arrays if no new data
**Error Responses:**
- 403 Forbidden → Show permission error message
- 404 Not Found → Show "not found" error message
- 400 Bad Request → Display validation errors from response
- 413 Request Entity Too Large → Show file size error
- 500 Internal Server Error → Show generic error message
---
## Field and Attribute Reference
### Complete Field List
The following is a comprehensive list of all parameters, attributes, and fields that will be displayed for workflows and user input. All of these are provided by the backend through the `/api/attributes/ChatWorkflow` and `/api/attributes/UserInputRequest` endpoints and should never be hardcoded in the frontend.
#### ChatWorkflow Fields
**Identification Fields:**
- `id` - Unique workflow identifier (text, readonly, not required, visible)
- `mandateId` - ID of the mandate this workflow belongs to (text, readonly, not required, visible)
- `name` - Workflow name (text, editable, not required, visible)
**Workflow Properties:**
- `status` - Workflow status (select, readonly, not required, visible)
- Options: "running", "completed", "stopped", "failed"
- Each option has localized labels (en/fr)
- `workflowMode` - Execution mode (select, readonly, not required, visible)
- Options: "Actionplan", "Dynamic", "Template"
- Each option has localized labels (en/fr)
- `currentRound` - Current user interaction round (number, readonly, not required, visible)
- `currentTask` - Current task in task plan (number, readonly, not required, visible)
- `currentAction` - Current action within task (number, readonly, not required, visible)
- `totalTasks` - Number of tasks in task plan (number, readonly, not required, visible)
- `totalActions` - Number of actions in current task (number, readonly, not required, visible)
- `maxSteps` - Maximum steps for Dynamic mode (number, readonly, not required, visible)
**Timestamp Fields:**
- `startedAt` - When workflow was created (timestamp, readonly, not required, visible)
- `lastActivity` - Last activity timestamp (timestamp, readonly, not required, visible)
**Related Data:**
- `messages` - List of ChatMessage objects (array, readonly, not required, visible)
- `logs` - List of ChatLog objects (array, readonly, not required, visible)
- `stats` - List of ChatStat objects (array, readonly, not required, visible)
- `tasks` - List of task objects (array, readonly, not required, visible)
#### UserInputRequest Fields
**Input Fields:**
- `prompt` - User prompt text (textarea, editable, required, visible)
- `listFileId` - Array of file IDs to attach (array, editable, not required, visible)
- `userLanguage` - User's preferred language (select, editable, not required, visible)
- Options: "en", "fr", etc.
- Each option has localized labels
#### Prompt Fields
**Prompt Properties:**
- `id` - Unique prompt identifier (text, readonly, not required, visible)
- `mandateId` - ID of the mandate this prompt belongs to (text, readonly, not required, visible)
- `name` - Prompt name (text, readonly, not required, visible)
- `content` - Prompt content (textarea, readonly, not required, visible)
### Attribute Definition Structure
Each field returned from `/api/attributes/ChatWorkflow` and `/api/attributes/UserInputRequest` contains:
- `name` - Field name (e.g., "status", "workflowMode", "prompt", "listFileId")
- `type` - Field data type (e.g., "text", "select", "textarea", "array", "timestamp", "number")
- `label` - Localized field label (object with language keys: {"en": "English Label", "fr": "French Label"})
- `description` - Field description text
- `required` - Boolean indicating if field is required
- `readonly` - Boolean indicating if field is read-only
- `editable` - Boolean indicating if field can be edited (inverse of readonly)
- `visible` - Boolean indicating if field should be displayed in UI
- `options` - Array of options for select fields (each option has `value` and localized `label`)
---
## Dynamic Rendering Guidelines
The frontend must render all UI components dynamically based on backend metadata. No field definitions, labels, validation rules, or UI structure should be hardcoded.
### Form Field Generation
When rendering input forms:
1. Fetch attribute definitions from `/api/attributes/UserInputRequest` and `/api/attributes/ChatWorkflow`
2. Filter attributes where `visible: true` AND `editable: true` to determine which fields to show
3. For each editable field, generate appropriate form input based on `type`:
- `text` fields → Text input
- `textarea` fields → Multi-line text area
- `select` fields → Dropdown/select input with options from `options` array (use localized labels)
- `array` fields → Array input with add/remove controls
- `number` fields → Number input
4. Use `label` property for field labels (localized)
5. Use `required` property to show required indicators (asterisk, etc.)
6. Use `description` property to show help text or tooltips
7. Validate form before submission:
- Check all `required: true` fields have values
- Validate types (e.g., array fields must be arrays)
- Validate select fields (value must be in options array)
8. On submit, build UserInputRequest object with all form data
### Workflow Mode Selector Generation
When rendering workflow mode selector:
1. Fetch attribute definitions from `/api/attributes/ChatWorkflow`
2. Find `workflowMode` field
3. Extract `options` array from field definition
4. Generate radio buttons or tabs for each option
5. Use localized labels from options: `option.label[userLanguage]`
6. Show description/help text when option is selected
7. Mark one option as required (user must select before starting)
### Dropdown Generation
**Workflow Dropdown:**
1. Fetch workflows via `GET /api/workflows/`
2. Display workflows in dropdown with name, status, last activity
3. Add "New Workflow" as default/first option
4. When workflow selected, load full workflow data
5. Display previous messages when workflow selected
**Prompt Dropdown:**
1. Fetch prompts via `GET /api/prompts`
2. Display prompts in dropdown with name
3. When prompt selected, fetch prompt details and pre-fill text field
4. Allow user to edit pre-filled text
### File Attachment UI Generation
**Drop Zone:**
1. Create drop zone area with visual boundaries
2. Handle drag events (dragenter, dragover, dragleave, drop)
3. Show visual feedback when files dragged over (highlight, border, overlay)
4. Process dropped files and upload automatically
5. Show file preview immediately after drop
**File Upload Button:**
1. Create file input element (hidden)
2. Trigger file picker on button click
3. Handle multiple file selection
4. Upload files and show preview
**File Browser:**
1. Fetch files via `GET /api/files/list`
2. Display files in browser/selector with pagination
3. Allow multiple file selection
4. Add selected files to attachment list
**File List Display:**
1. Show attached files with name, size, type
2. Display remove button for each file
3. Update list when files added or removed
### Message Display Generation
When rendering messages in workflow view:
1. Fetch messages from workflow data or chatData endpoint
2. Display messages chronologically
3. Format based on message role:
- User messages → Right-aligned or distinct styling
- Assistant messages → Left-aligned or distinct styling
4. Display file attachments as part of each message:
- Show file name, size, and type/icon for each attachment
- Display file attachments in organized list or grid within message
- For each file attachment, render action buttons:
- **"Show" button** - Opens file preview/viewer
- **"Download" button** - Triggers file download
- **"Delete" button** - Removes file from message (with confirmation)
- File preview can be displayed inline, in modal, or sidebar
- Support different file type previews (images, PDFs, text, etc.)
5. Show timestamps (relative or absolute)
6. Add delete button for each message (if user has permission)
### Log Display Generation
When rendering logs in log panel:
1. Fetch logs from workflow data or chatData endpoint
2. Display logs chronologically
3. Format based on log level:
- Info → Default styling
- Warning → Yellow/orange styling
- Error → Red styling
4. Show timestamps for each log entry
5. Support filtering by log level (optional)
### Statistics Display Generation
When rendering statistics in stats panel:
1. Fetch stats from workflow data or chatData endpoint
2. Display statistics in organized format
3. Format based on metric type:
- Numbers → Display with appropriate units
- Percentages → Display as percentage
- Timestamps → Format as duration or absolute time
4. Update statistics in real-time during polling
### Display Formatting
When displaying field values:
1. Use `type` property to determine formatting:
- `text` → Display as-is (may need HTML escaping)
- `textarea` → Preserve line breaks
- `select` → Look up value in `options` array and display localized label
- `timestamp` → Format as relative time or absolute date/time
- `number` → Format with appropriate decimal places
- `array` → Display as list or comma-separated
2. Handle `null` or `undefined` values gracefully (show "-" or "Not set")
3. Use `readonly` property to determine if field should show edit indicators
4. Special formatting for workflow fields:
- Status → Color-code badges (Running = blue, Completed = green, Stopped = gray, Failed = red)
- Workflow Mode → Display as badge with icon
- Timestamps → Show relative time in list view, absolute date in detail view
### Localization
All labels and options support multiple languages:
1. Use user's preferred language (from user settings or browser locale)
2. Access localized labels from `label` object: `label[userLanguage]` or `label.en` as fallback
3. For select options, use `option.label[userLanguage]` or `option.label.en` as fallback
4. If label for current language is missing, fall back to English
### Polling Implementation
**Polling Setup:**
1. Start polling when workflow view is active
2. Use `setInterval` or similar mechanism (2 second interval)
3. Store last timestamp to use in `afterTimestamp` parameter
4. Stop polling when workflow completes or user navigates away
**Polling Logic:**
1. Call `GET /api/chat/playground/{workflowId}/chatData?afterTimestamp={lastTimestamp}`
2. Compare returned data with existing data
3. Append new messages, logs, stats to UI
4. Update last timestamp
5. Check workflow status - stop polling if completed/stopped/failed
6. Handle errors gracefully (404 stops polling)
**Performance Considerations:**
1. Debounce rapid updates
2. Batch UI updates
3. Use virtual scrolling for long message lists
4. Limit polling frequency
5. Stop polling when tab is not visible (Page Visibility API)
### Key Principles
- Never hardcode field names, labels, types, or validation rules
- Always fetch attribute definitions from backend before rendering UI
- Use attribute metadata to determine what to display and how to display it
- Support all field types dynamically - if backend adds new types, frontend should handle them
- Respect `visible`, `editable`, `readonly`, and `required` flags from backend
- Use localized labels from backend metadata
- Generate forms, dropdowns, and displays entirely from attribute definitions
- When backend adds new fields, frontend should automatically display them without code changes
- Handle all error cases gracefully (403, 404, 400, 413, 500)
- Provide user feedback for all actions (loading states, success messages, error messages)
- **All workflows are user-scoped** (backend enforces this)
- **Polling should be efficient** (use selective data transfer with afterTimestamp)
- **Optimistic updates** for better UX (show changes immediately, revert on error)
---
## Summary
This document provides complete frontend requirements for the chat playground page and workflow management components. All requirements follow the principle of **backend-driven UI generation**—no hardcoding of field definitions, labels, or validation rules. The frontend should dynamically generate all UI components from backend metadata provided through the `/api/attributes/ChatWorkflow` and `/api/attributes/UserInputRequest` endpoints.
**Key Architecture Pattern:** The chat playground interface is a single page (`/chat-playground`) with different views managed through component state. All interactions happen within the same page component without separate routes.
**Security Note:** Workflows are user-scoped. Users can only see and manage their own workflows. The backend enforces this security, and the frontend should never attempt to access other users' workflows.
**Real-Time Updates:** The workflow view uses polling-based live tracking to show real-time updates. Polling should be efficient using selective data transfer with timestamps.
For generic patterns that apply across all entity types (not just workflows), see the [Dynamic Forms and Pagination documentation](./dynamic-forms-and-pagination.md).
Reference in a new issue View git blame Copy permalink