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

# File Routes Frontend Documentation

This document describes customer journeys for managing files through the frontend, focusing on how users interact with file 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 Files](#customer-journey-1-discovering-and-browsing-files)
3. [Customer Journey 2: Uploading Files](#customer-journey-2-uploading-files)
4. [Customer Journey 3: Editing File Properties](#customer-journey-3-editing-file-properties)
5. [Customer Journey 4: Downloading Files](#customer-journey-4-downloading-files)
6. [Customer Journey 5: Adding File to Prompt](#customer-journey-5-adding-file-to-prompt)
7. [Customer Journey 6: Deleting Files](#customer-journey-6-deleting-files)

---

## Overview

The file routes (`/api/files`) enable users to manage files within their mandate. These routes focus on **file administration** including upload, editing, download, preview, 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**: Files are managed within the context of mandates

---

## Customer Journey 1: Discovering and Browsing Files

### User Goal
"I want to see all files in my mandate and find the one I'm looking for."

### User Story
As a user, I want to browse files, search for specific files, filter by any field, sort them by different criteria, and quickly identify files by their name, size, type, and creation date.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Navigate to /files
    Frontend->>Backend: GET /api/attributes/FileItem
    Backend-->>Frontend: Attribute definitions (fields, labels, types)
    Frontend->>Backend: GET /api/files/list?pagination=...
    Backend-->>Frontend: Paginated files list
    Frontend->>Frontend: Generate table columns from attributes
    Frontend->>Frontend: Generate filter controls from attributes
    Frontend->>Frontend: Render files table + search + filters
    Frontend->>Frontend: Render action buttons in table (Edit, Delete, Download, Add to Prompt)
    Frontend-->>User: Display file 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/files/list?pagination=...filters:{"search":"invoice"}
        Backend-->>Frontend: Filtered files list
        Frontend-->>User: Display matching files
    end
    
    alt User applies field filter
        User->>Frontend: Select filter field (e.g., "MIME Type")
        Frontend->>Frontend: Show filter options from attribute metadata
        User->>Frontend: Select filter value (e.g., "application/pdf")
        Frontend->>Frontend: Update filter parameters
        Frontend->>Backend: GET /api/files/list?pagination=...filters:{"mimeType":"application/pdf"}
        Backend-->>Frontend: Filtered files list
        Frontend-->>User: Display filtered files
    end
    
    alt User combines search + filter + sort
        User->>Frontend: Apply search + filter + sort
        Frontend->>Frontend: Combine all parameters
        Frontend->>Backend: GET /api/files/list?pagination=...filters:{"search":"invoice","mimeType":"application/pdf"}...sort:desc
        Backend-->>Frontend: Filtered, sorted files list
        Frontend-->>User: Display results
    end
    
    User->>Frontend: Click column header (e.g., "File Size")
    Frontend->>Frontend: Update sort parameters
    Frontend->>Backend: GET /api/files/list?pagination=...sort:desc
    Backend-->>Frontend: Sorted files list
    Frontend-->>User: Display sorted files
```

---

## Customer Journey 2: Uploading Files

### User Goal
"I want to upload new files to my mandate."

### User Story
As a user, I want to upload files by selecting them from my device. The system should validate file size, handle duplicates, and show clear feedback about the upload status.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    alt User clicks "Upload File" button
        User->>Frontend: Click "Upload File" button
        Frontend->>Frontend: Show file upload dialog/input
        Frontend-->>User: Display file picker
        User->>Frontend: Select file(s) from device
    else User drags and drops files
        User->>Frontend: Drag file(s) over upload area
        Frontend->>Frontend: Highlight drop zone
        User->>Frontend: Drop file(s) on upload area
        Frontend->>Frontend: Accept dropped files
    end
    
    Frontend->>Frontend: Optimistic update: Show loading state, add file to UI immediately
    Frontend->>Backend: POST /api/files/upload + file data
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend->>Frontend: Revert optimistic update: Remove file from UI
        Frontend-->>User: Show permission error
    else Success (201)
        Backend-->>Frontend: Created file object + duplicate info
        Frontend->>Frontend: Keep optimistic update
        Frontend->>Backend: GET /api/files/list?pagination=... (refetch)
        Backend-->>Frontend: Updated files list
        Frontend->>Frontend: Update table with fresh data
        Frontend-->>User: Show success message (with duplicate info if applicable)
    end
```

---

## Customer Journey 3: Editing File Properties

### User Goal
"I want to change the file name through an edit form."

### User Story
As a user, I want to edit a file's name through a popup/modal form, with validation and clear error messages.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Edit" button in table row
    Frontend->>Backend: GET /api/files/fileId
    Backend-->>Frontend: Current file data
    
    Frontend->>Backend: GET /api/attributes/FileItem
    Backend-->>Frontend: Field definitions (editable fields)
    
    Frontend->>Frontend: Filter editable fields
    Frontend->>Frontend: Generate form from attributes
    Frontend->>Frontend: Pre-populate form with file data
    Frontend->>Frontend: Open popup/modal with edit form
    Frontend-->>User: Display edit form in popup/modal
    
    User->>Frontend: Modify file name
    User->>Frontend: Click "Save"
    
    Frontend->>Frontend: Validate form (required fields, types)
    alt Validation fails
        Frontend-->>User: Show validation errors in modal
    else Validation passes
        Frontend->>Frontend: Optimistic update: Apply changes to UI immediately
        Frontend->>Backend: PUT /api/files/fileId + form data
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show permission error in modal
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request + error details
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>User: Show backend validation errors in modal
        else Success (200)
            Backend-->>Frontend: Updated file
            Frontend->>Frontend: Keep optimistic update (or refresh from response)
            Frontend->>Backend: GET /api/files/list?pagination=... (refetch)
            Backend-->>Frontend: Updated files list
            Frontend->>Frontend: Update table with fresh data
            Frontend->>Frontend: Close popup/modal
            Frontend-->>User: Show updated file name in table
        end
    end
    
    alt User clicks Cancel
        User->>Frontend: Click "Cancel" button
        Frontend->>Frontend: Close popup/modal without saving
        Frontend-->>User: Modal closed, no changes
    end
```

---

## Customer Journey 4: Downloading Files

### User Goal
"I want to download files to my device."

### User Story
As a user, I want to download files by clicking a download button, so I can save them locally on my device.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Download" button in table
    Frontend->>Frontend: Show loading state
    Frontend->>Backend: GET /api/files/fileId/download
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend-->>User: Show permission error
    else File not found (404)
        Backend-->>Frontend: 404 Not Found
        Frontend-->>User: Show not found error
    else Success (200)
        Backend-->>Frontend: File content with Content-Disposition header
        Frontend->>Frontend: Trigger browser download
        Frontend-->>User: File downloads to device
    end
```

---

## Customer Journey 5: Adding File to Prompt

### User Goal
"I want to use a file with a prompt in the chat playground."

### User Story
As a user, I want to add a file to the chat playground so I can use it with a prompt to start a workflow.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Add to Prompt" button in table
    Frontend->>Backend: GET /api/files/fileId
    Backend-->>Frontend: File object (id, fileName)
    
    Frontend->>Frontend: Navigate to /chat-playground
    Frontend->>Frontend: Pre-select file in file picker/attachments
    Frontend->>Frontend: Show file name as context
    Frontend-->>User: Display chat playground with file attached
    
    User->>Frontend: Enter prompt text
    User->>Frontend: Optionally add more files
    User->>Frontend: Click "Start" or "Send" button
    
    Frontend->>Frontend: Validate user input (prompt required)
    alt Validation fails
        Frontend-->>User: Show validation errors
    else Validation passes
        Frontend->>Backend: POST /api/chat/playground/start?workflowMode=Dynamic<br/>Body: {prompt: userPrompt, listFileId: [fileId, ...], 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 Files

### User Goal
"I want to delete files that are no longer needed."

### User Story
As a user, I want to delete files 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/files/fileId
    Backend-->>Frontend: File data (for name)
    Frontend->>Frontend: Show confirmation dialog<br/>"Delete 'File Name'?"
    User->>Frontend: Cancel deletion
    Frontend-->>User: Dialog closed, no action
    
    User->>Frontend: Click "Delete" button again
    Frontend->>Backend: GET /api/files/fileId
    Backend-->>Frontend: File data
    Frontend->>Frontend: Show confirmation dialog
    User->>Frontend: Confirm deletion
    Frontend->>Frontend: Optimistic update: Remove file from UI immediately
    Frontend->>Backend: DELETE /api/files/fileId
    
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend->>Frontend: Revert optimistic update: Restore file in UI
        Frontend-->>User: Show permission error
    else Not found (404)
        Backend-->>Frontend: 404 Not Found
        Frontend->>Frontend: Revert optimistic update: Restore file in UI
        Frontend-->>User: Show not found error
    else Success (200)
        Backend-->>Frontend: Success response
        Frontend->>Frontend: Keep optimistic update (file already removed)
        Frontend->>Frontend: Show success message
        Frontend->>Frontend: Navigate to /files (if on detail page)
        Frontend-->>User: Display file list (without deleted file)
    end
```