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

# Connection Routes Frontend Documentation

This document describes customer journeys for managing connections through the frontend, focusing on how users interact with connection 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 Connections](#customer-journey-1-discovering-and-browsing-connections)
3. [Customer Journey 2: Creating New Connections](#customer-journey-2-creating-new-connections)
4. [Customer Journey 3: Editing Connection Properties](#customer-journey-3-editing-connection-properties)
5. [Customer Journey 4: Refreshing Connection Tokens](#customer-journey-4-refreshing-connection-tokens)
6. [Customer Journey 5: Deleting Connections](#customer-journey-5-deleting-connections)

---

## Overview

The connection routes (`/api/connections`) enable users to manage their OAuth connections (Google, Microsoft) within their account. These routes focus on **connection administration** including creation, editing, token refresh, 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 connections

---

## Customer Journey 1: Discovering and Browsing Connections

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

### User Story
As a user, I want to browse my connections, search for specific connections, filter by any field, sort them by different criteria, and quickly identify connections by their authority, status, and token status.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Navigate to /connections
    Frontend->>Backend: GET /api/attributes/UserConnection
    Backend-->>Frontend: Attribute definitions (fields, labels, types)
    Frontend->>Backend: GET /api/connections/
    Backend-->>Frontend: Connections list (with token status)
    Frontend->>Frontend: Generate table columns from attributes
    Frontend->>Frontend: Generate filter controls from attributes
    Frontend->>Frontend: Render connections table + search + filters
    Frontend->>Frontend: Render action buttons in table (Edit, Delete, Refresh Token)
    Frontend-->>User: Display connection list with search/filter UI + action buttons
    
    alt User performs general search
        User->>Frontend: Type in search box (e.g., "google")
        Frontend->>Frontend: Update search query
        Frontend->>Backend: GET /api/connections/ (client-side filter)
        Frontend-->>User: Display matching connections
    end
    
    alt User applies field filter
        User->>Frontend: Select filter field (e.g., "Authority")
        Frontend->>Frontend: Show filter options from attribute metadata
        User->>Frontend: Select filter value (e.g., "google")
        Frontend->>Frontend: Update filter parameters
        Frontend->>Backend: GET /api/connections/ (client-side filter)
        Frontend-->>User: Display filtered connections
    end
    
    alt User combines search + filter + sort
        User->>Frontend: Apply search + filter + sort
        Frontend->>Frontend: Combine all parameters
        Frontend->>Backend: GET /api/connections/ (client-side filter/sort)
        Frontend-->>User: Display results
    end
    
    User->>Frontend: Click column header (e.g., "Status")
    Frontend->>Frontend: Update sort parameters
    Frontend->>Backend: GET /api/connections/ (client-side sort)
    Backend-->>Frontend: Connections list
    Frontend-->>User: Display sorted connections
```

---

## Customer Journey 2: Creating New Connections

### User Goal
"I want to create new OAuth connections for my account."

### User Story
As a user, I want to create a new connection by clicking either "Connect Google" or "Connect Microsoft" button, which will immediately initiate the OAuth flow.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    alt User clicks "Connect Google" button
        User->>Frontend: Click "Connect Google" button
        Frontend->>Frontend: Optimistic update: Show loading state, add connection to UI immediately
        Frontend->>Backend: POST /api/connections/ + {type: "google"}
    else User clicks "Connect Microsoft" button
        User->>Frontend: Click "Connect Microsoft" button
        Frontend->>Frontend: Optimistic update: Show loading state, add connection to UI immediately
        Frontend->>Backend: POST /api/connections/ + {type: "msft"}
    end
    
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend->>Frontend: Revert optimistic update: Remove connection from UI
        Frontend-->>User: Show permission error
    else Validation error (400)
        Backend-->>Frontend: 400 Bad Request + error details
        Frontend->>Frontend: Revert optimistic update: Remove connection from UI
        Frontend-->>User: Show backend validation errors
    else Success (200)
        Backend-->>Frontend: Created connection object (status: PENDING)
        Frontend->>Frontend: Keep optimistic update
        Frontend->>Backend: POST /api/connections/connectionId/connect
        Backend-->>Frontend: {authUrl: "/api/google/login?state=..."} or {authUrl: "/api/msft/login?state=..."}
        Frontend->>Frontend: Navigate to authUrl (OAuth flow)
        Frontend-->>User: Redirect to OAuth provider
    end
```

---

## Customer Journey 3: Editing Connection Properties

### User Goal
"I want to change connection settings like its status or external email."

### User Story
As a user, I want to edit a connection's properties through a popup/modal 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 in table row
    Frontend->>Backend: GET /api/connections/connectionId
    Backend-->>Frontend: Current connection data
    
    Frontend->>Backend: GET /api/attributes/UserConnection
    Backend-->>Frontend: Field definitions (editable fields)
    
    Frontend->>Frontend: Filter editable fields
    Frontend->>Frontend: Generate form from attributes
    Frontend->>Frontend: Pre-populate form with connection data
    Frontend->>Frontend: Open popup/modal with edit form
    Frontend-->>User: Display edit form in popup/modal
    
    User->>Frontend: Modify form fields
    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/connections/connectionId + 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 connection
            Frontend->>Frontend: Keep optimistic update (or refresh from response)
            Frontend->>Backend: GET /api/connections/ (refetch)
            Backend-->>Frontend: Updated connections list
            Frontend->>Frontend: Update table with fresh data
            Frontend->>Frontend: Close popup/modal
            Frontend-->>User: Show updated connection 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: Refreshing Connection Tokens

### User Goal
"I want to refresh the OAuth token for a connection that is expired or about to expire."

### User Story
As a user, I want to refresh the OAuth token for a connection by clicking a refresh button, so the connection remains active.

### User Story Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant Backend
    
    User->>Frontend: Click "Refresh Token" button in table
    Frontend->>Frontend: Show loading state
    Frontend->>Frontend: Optimistic update: Update token status to "refreshing"
    
    alt Connection authority is Microsoft
        Frontend->>Backend: POST /api/msft/refresh + {connectionId: connectionId}
    else Connection authority is Google
        Frontend->>Backend: POST /api/google/refresh + {connectionId: connectionId}
    end
    
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend->>Frontend: Revert optimistic update
        Frontend-->>User: Show permission error
    else Connection not found (404)
        Backend-->>Frontend: 404 Not Found
        Frontend->>Frontend: Revert optimistic update
        Frontend-->>User: Show not found error
    else Success (200)
        Backend-->>Frontend: {message: "Token refreshed successfully", expires_at: timestamp, expires_in_seconds: number}
        Frontend->>Frontend: Keep optimistic update
        Frontend->>Backend: GET /api/connections/ (refetch)
        Backend-->>Frontend: Updated connections list with new token status
        Frontend->>Frontend: Update table with fresh data
        Frontend-->>User: Show success message, updated token status
    end
```

---

## Customer Journey 5: Deleting Connections

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

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