gateway/docs/frontend-documentation/connection-page-requirements.md

# Connection Page Requirements

This document contains the complete frontend requirements for all connection management pages and 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 connection management page enables users to manage their OAuth connections (Google, Microsoft) within their account. The frontend consists of a single page (`/connections`) with different views/states:

- **List View** - Browse, search, filter, and sort connections (all information displayed in table)
- **Edit View** - Edit connection properties in popup/modal

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/UserConnection` endpoint. Views are managed through component state and routing within the same page, not as separate routes.

**Note:** Connections are user-scoped. Users can only see and manage their own connections. The backend enforces this security.

---

## Page Structure and Layout

### Connection Management Page (`/connections`)

The connection management page uses different views/states to handle different user interactions. Views are managed through component state and routing within the same page component.

### List View

**State:** `view === 'list'` or `selectedConnectionId === null`

**What the user sees:**

- **Main Content Area:**
  - Table or card grid displaying all connections for the current user
  - Each connection row/card shows: authority, external username, external email, status, token status, connected at, last checked
  - **Action buttons column** in table (rendered on first load):
    - "Edit" button - opens popup/modal edit form
    - "Delete" button - shows confirmation dialog and deletes connection
    - "Refresh Token" button - refreshes OAuth token for the connection
  - All necessary connection information displayed in table (no detail view needed)

- **Search and Filter Controls:**
  - General search input box (searches across all text fields)
  - Field-specific filter controls (one filter per visible field)
  - Active filter indicators (chips/badges showing applied filters)
  - "Clear all filters" button when filters are active
  - **Note:** Filtering and sorting are done client-side (connections endpoint returns all user connections)

- **Sorting Controls:**
  - Clickable column headers with sort indicators (up/down arrows)
  - Visual indication of current sort field and direction
  - Support for multi-level sorting
  - **Note:** Sorting is done client-side

- **Action Buttons:**
  - "Connect Google" button - creates Google connection and initiates OAuth flow
  - "Connect Microsoft" button - creates Microsoft connection and initiates OAuth flow

### Edit View (Popup/Modal)

**State:** `view === 'edit'` and `selectedConnectionId !== null` (popup/modal overlay)

**What the user sees:**

- **Edit Form in Popup/Modal:**
  - Dynamic form with editable connection fields only
  - Field labels with required indicators (asterisk for required fields)
  - Help text/tooltips from field descriptions
  - Input validation errors displayed inline
  - Form pre-populated with current connection values
  - Save and Cancel buttons in modal footer
  - On save: Updates connection, closes modal, refreshes table
  - On cancel: Closes modal without saving

- **Confirmation Dialogs:**
  - Delete confirmation dialog

---

## User Interactions and Functionality

### Browsing and Discovery

**Search Functionality:**
- User types in general search box
- Frontend debounces input (300-500ms delay)
- Search applies across all text fields in connection objects
- **Client-side filtering** (connections endpoint returns all user connections)
- Results update automatically

**Field Filtering:**
- User selects field to filter by
- Frontend shows appropriate filter UI based on field type:
  - Text fields → Text input with operator selection (contains, equals, startsWith, endsWith)
  - Select fields → Dropdown with options from backend metadata
  - Timestamp fields → Date picker with comparison operators or date range picker
- User applies filter → Filter appears as active chip/badge
- User can remove individual filters
- Multiple filters work together (AND logic)
- **Client-side filtering** (no backend pagination)

**Sorting:**
- User clicks column header
- Sort direction toggles (asc → desc → remove)
- Multiple columns can be sorted (multi-level sorting)
- Sort indicators show on column headers
- All filters and search preserved when sorting
- **Client-side sorting** (no backend pagination)

**View Switching:**
- All connection information displayed in table (no detail view navigation needed)

### Creating Connections

**Create Interaction:**
- User clicks "Connect Google" button → Immediately creates Google connection and initiates OAuth flow
- OR user clicks "Connect Microsoft" button → Immediately creates Microsoft connection and initiates OAuth flow
- No dialog or selection step needed

**Connection Creation:**
- Connection created with PENDING status
- OAuth flow automatically initiated via `/api/connections/{connectionId}/connect`
- User redirected to OAuth provider
- After OAuth completion, connection status updated to ACTIVE

**Connection Submission:**
- For Google: Connection type sent as `{type: "google"}`
- For Microsoft: Connection type sent as `{type: "msft"}`
- Success → Connection created, OAuth flow initiated, user redirected
- Error handling:
  - 403 (permission denied) → Show permission error
  - 400 (validation errors) → Display backend validation errors
  - Other errors → Show generic error message

### Editing Connections

**Edit Interaction:**
- User clicks "Edit" button in table row → Opens popup/modal edit form
- Form pre-populated with current connection values
- User modifies fields (typically externalEmail, status)
- Client-side validation shows errors immediately
- User clicks Save → Form validates and submits
- User clicks Cancel → Closes modal without saving

**Form Validation:**
- Required field validation (shows error if empty)
- Type validation (e.g., email fields must be valid email format)
- Select field validation (value must be in options array)
- Validation errors displayed inline below fields

**Form Submission:**
- Only changed fields sent (or all form data)
- Success → Close popup/modal, refresh table, show success message
- Error handling:
  - 403 (permission denied) → Show permission error in modal
  - 400 (validation errors) → Display backend validation errors in modal
  - Other errors → Show generic error message in modal

### Refreshing Connection Tokens

**Refresh Token Action:**
- User clicks "Refresh Token" button in table
- Frontend shows loading state
- Frontend determines connection authority (Google or Microsoft)
- Frontend calls appropriate refresh endpoint:
  - Microsoft: `POST /api/msft/refresh` with `{connectionId: connectionId}`
  - Google: `POST /api/google/refresh` with `{connectionId: connectionId}`
- Success → Token refreshed, connection status updated, table refreshed
- Error handling:
  - 403 (permission denied) → Show permission error
  - 404 (connection not found) → Show not found error
  - Other errors → Show generic error message

**Implementation Notes:**
- Refresh button should be disabled or show loading state during refresh
- Token status should update immediately after successful refresh
- Connection status may change from "expired" to "active" after refresh

### Deleting Connections

**Delete Action:**
- User clicks delete button in table
- Confirmation dialog appears with connection authority/type
- Warning about permanent deletion
- User confirms → Connection deleted
- User cancels → Dialog closes, no action

**Delete Success Handling:**
- Success message displayed
- Remove connection from list or refresh table

---

## Backend Routes and API Integration

### Complete Route Reference

All backend routes used by connection pages:

| Route | Method | Purpose | When Used | Access Control |
|-------|--------|---------|-----------|----------------|
| `/api/connections/` | GET | Get all connections for current user | Initial page load | Current user only (returns only user's connections) |
| `/api/connections/` | POST | Create new connection | User selects connection type | Current user only |
| `/api/connections/{connectionId}` | PUT | Update connection | Edit form submission | Current user only |
| `/api/connections/{connectionId}` | DELETE | Delete connection | User confirms deletion | Current user only |
| `/api/connections/{connectionId}/connect` | POST | Initiate OAuth flow | After connection creation | Current user only |
| `/api/msft/refresh` | POST | Refresh Microsoft token | User clicks refresh token for MSFT connection | Current user only |
| `/api/google/refresh` | POST | Refresh Google token | User clicks refresh token for Google connection | Current user only |
| `/api/attributes/UserConnection` | GET | Get field definitions | Page load (once per page) - used to generate all UI components | All authenticated users |

### API Request Patterns

**Get Connections Request:**
```
GET /api/connections/
```
- Returns all connections for the current user (no pagination)
- Response includes token status information
- Filtering and sorting done client-side

**Create Connection Request:**
```
POST /api/connections/
Content-Type: application/json
Body: {
  "type": "google" | "msft"
}
```
- Creates connection with PENDING status
- Returns created connection object
- Handle 403 (permission denied) and 400 (validation errors)

**Connect Service Request:**
```
POST /api/connections/{connectionId}/connect
```
- Returns `{authUrl: "/api/google/login?state=..."}` or `{authUrl: "/api/msft/login?state=..."}`
- Frontend should navigate to the authUrl to initiate OAuth flow
- Called automatically after connection creation

**Update Request:**
```
PUT /api/connections/{connectionId}
Content-Type: application/json
Body: {fieldName: value, ...}
```
- Send only changed fields or all form data
- Handle 403 (permission denied) and 400 (validation errors)

**Refresh Token Request:**
```
POST /api/msft/refresh
Content-Type: application/json
Body: {"connectionId": "connection-id"}
```
OR
```
POST /api/google/refresh
Content-Type: application/json
Body: {"connectionId": "connection-id"}
```
- Returns `{message: "Token refreshed successfully", expires_at: timestamp, expires_in_seconds: number}`
- Handle 403 (permission denied) and 404 (connection not found)

**Delete Requests:**
```
DELETE /api/connections/{connectionId}
```
- Delete operation requires user confirmation
- Handle 403 (permission denied) and 404 (not found) gracefully

### Response Handling

**Get Connections Response:**
```json
[
  {
    "id": "...",
    "userId": "...",
    "authority": "google",
    "externalId": "...",
    "externalUsername": "...",
    "externalEmail": "...",
    "status": "active",
    "connectedAt": 1234567890,
    "lastChecked": 1234567890,
    "expiresAt": 1234567890,
    "tokenStatus": "active",
    "tokenExpiresAt": 1234567890
  },
  ...
]
```
- Returns array of connections (no pagination)
- Each connection includes token status information

**Error Responses:**
- 403 Forbidden → Show permission error message
- 404 Not Found → Show "not found" error message
- 400 Bad Request → Display validation errors from response
- 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 connections. All of these are provided by the backend through the `/api/attributes/UserConnection` endpoint and should never be hardcoded in the frontend.

#### Core Connection Fields

**Identification Fields:**
- `id` - Unique connection identifier (text, readonly, not required, visible)
- `userId` - ID of the user this connection belongs to (text, readonly, not required, visible)

**Connection Properties:**
- `authority` - Authentication authority (select, readonly, not required, visible)
  - Options: "local", "google", "msft"
  - Each option has localized labels (en/fr)
- `externalId` - User ID in the external system (text, readonly, not required, visible)
- `externalUsername` - Username in the external system (text, editable, required, visible)
- `externalEmail` - Email in the external system (email, editable, not required, visible)
- `status` - Connection status (select, editable, not required, visible)
  - Options: "active", "inactive", "expired", "pending"
  - Each option has localized labels (en/fr)

**Timestamp Fields:**
- `connectedAt` - When the connection was established (timestamp, readonly, not required, visible)
- `lastChecked` - When the connection was last verified (timestamp, readonly, not required, visible)
- `expiresAt` - When the connection expires (timestamp, readonly, not required, visible)

**Token Status Fields:**
- `tokenStatus` - Current token status (select, readonly, not required, visible)
  - Options: "active", "expired", "none"
  - Each option has localized labels (en/fr)
- `tokenExpiresAt` - When the current token expires (timestamp, readonly, not required, visible)

### Attribute Definition Structure

Each field returned from `/api/attributes/UserConnection` contains:

- `name` - Field name (e.g., "authority", "status", "externalEmail", "id")
- `type` - Field data type (e.g., "text", "select", "email", "timestamp", "checkbox")
- `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.

### Table Column Generation

When rendering the connection list table:

1. Fetch attribute definitions from `/api/attributes/UserConnection`
2. Filter attributes where `visible: true` to determine which columns to display
3. Use `label` property for column headers (select appropriate language based on user preference)
4. Use `type` property to determine how to format cell values:
   - `text` fields → Display as plain text
   - `email` fields → Display as clickable mailto link
   - `select` fields → Display value using label from options array (match value to option.value, then display option.label)
   - `timestamp` fields → Format as relative time ("2 hours ago") or absolute date/time based on user preference
   - `checkbox` fields → Display as checkmark icon or "Yes"/"No" text
5. Use `readonly` property to determine if column should be sortable (readonly fields may still be sortable, but editable fields definitely are)
6. Generate click handlers for column headers to update sort parameters (client-side sorting)
7. **Add Actions Column:**
   - Render action buttons in each table row on first load
   - Include "Edit" button - opens popup/modal edit form
   - Include "Delete" button - shows confirmation dialog
   - Include "Refresh Token" button - refreshes OAuth token (only for Google/MSFT connections)
   - Buttons should be visible and accessible in each row

### Filter Control Generation

When rendering filter controls:

1. Fetch attribute definitions from `/api/attributes/UserConnection`
2. Filter attributes where `visible: true` to determine which filters to show
3. For each visible field, generate appropriate filter UI based on `type`:
   - `text` fields → Text input filter (supports "contains", "equals", "startsWith", "endsWith" operators)
   - `email` fields → Email input filter
   - `select` fields → Dropdown filter with options from `options` array (use localized labels)
   - `timestamp` fields → Date range picker or single date picker with comparison operators
   - `checkbox` fields → Boolean toggle filter (true/false/any)
4. Use `label` property for filter labels (localized)
5. When user applies filter, update client-side filter state
6. Display active filters as chips/badges showing field label and value
7. Allow removing individual filters
8. **Note:** All filtering is done client-side (connections endpoint returns all user connections)

### Search Implementation

For general search functionality:

1. Display a single search input box (not field-specific)
2. When user types, update client-side search state
3. Debounce search input (wait 300-500ms after user stops typing before filtering)
4. Search applies across all text fields in the connection object
5. **Note:** All searching is done client-side (connections endpoint returns all user connections)

### Form Field Generation

When rendering edit forms:

1. Fetch attribute definitions from `/api/attributes/UserConnection`
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
   - `email` fields → Email input
   - `select` fields → Dropdown/select input with options from `options` array (use localized labels)
   - `timestamp` fields → Date/time picker
   - `checkbox` fields → Checkbox 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., email fields must be valid email format)
   - Validate select fields (value must be in options array)
8. On submit, send only changed fields or all form data to update endpoint

### Display Formatting

When displaying field values:

1. Use `type` property to determine formatting:
   - `text` → Display as-is (may need HTML escaping)
   - `email` → Display as clickable mailto link
   - `select` → Look up value in `options` array and display localized label
   - `timestamp` → Format as relative time or absolute date/time
   - `checkbox` → Display as checkmark icon or "Yes"/"No" text
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 connection fields:
   - Authority → Display as badge with icon (Google, Microsoft)
   - Status → Color-code badges (Active = green, Inactive = gray, Expired = red, Pending = yellow)
   - Token Status → Color-code badges (Active = green, Expired = red, None = gray)
   - 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

### 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 filters, forms, and tables 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, 500)
- Provide user feedback for all actions (loading states, success messages, error messages)
- **All filtering and sorting is done client-side** (connections endpoint returns all user connections)
- **Users can only see and manage their own connections** (backend enforces this)

---

## Summary

This document provides complete frontend requirements for all connection management pages and 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/UserConnection` endpoint.

**Key Architecture Pattern:** The connection management interface is a single page (`/connections`) with different views managed through component state. All interactions happen within the same page component without separate routes.

**Security Note:** Connections are user-scoped. Users can only see and manage their own connections. The backend enforces this security, and the frontend should never attempt to access other users' connections.

For generic patterns that apply across all entity types (not just connections), see the [Dynamic Forms and Pagination documentation](./dynamic-forms-and-pagination.md).