# User Routes Frontend Documentation

This document describes customer journeys for managing users through the frontend, focusing on how administrators interact with user management and how the backend routes support these experiences. All UI components are dynamically generated from backend metadata—no hardcoding required.

**IMPORTANT:** All user management pages are **admin-only**. Non-admin users should not see navigation links or be able to access these pages. The frontend must check user privileges before rendering user management UI.

## Table of Contents

1. [Overview](#overview)
2. [Customer Journey 1: Discovering and Browsing Users](#customer-journey-1-discovering-and-browsing-users)
3. [Customer Journey 2: Viewing User Details](#customer-journey-2-viewing-user-details)
4. [Customer Journey 3: Creating New Users](#customer-journey-3-creating-new-users)
5. [Customer Journey 4: Editing User Properties](#customer-journey-4-editing-user-properties)
6. [Customer Journey 5: Enabling and Disabling Users](#customer-journey-5-enabling-and-disabling-users)
7. [Customer Journey 6: Resetting User Passwords](#customer-journey-6-resetting-user-passwords)
8. [Customer Journey 7: Revoking User Sessions](#customer-journey-7-revoking-user-sessions)
9. [Customer Journey 8: Deleting Users](#customer-journey-8-deleting-users)
9. [Backend Metadata System](#backend-metadata-system)
10. [Implementation Patterns](#implementation-patterns)

---

## Overview

The user routes (`/api/users`) enable administrators to manage users within their mandate. These routes focus on **user administration** including creation, editing, password management, and deletion.

**Key Principles:**
- **Admin-Only**: All user management functionality is restricted to administrators
- **User-Centric**: Documentation organized around what administrators 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**: Users are managed within the context of mandates

---

## Customer Journey 1: Discovering and Browsing Users

### User Goal
"As an administrator, I want to see all users in my mandate and find the one I'm looking for."

### User Story
As an administrator, I want to browse users, search for specific users, filter by any field, sort them by different criteria, and quickly identify which users are enabled, their privilege levels, and their authentication methods.

### User Story Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: Navigate to /users (admin only)
    Frontend->>Frontend: Check if user is admin
    alt User is not admin
        Frontend-->>Admin: Redirect to unauthorized page or hide navigation
    else User is admin
        Frontend->>Backend: GET /api/attributes/User
        Backend-->>Frontend: Attribute definitions (fields, labels, types)
        Frontend->>Backend: GET /api/users/?pagination=...
        Backend-->>Frontend: Paginated users list
        Frontend->>Frontend: Generate table columns from attributes
        Frontend->>Frontend: Generate filter controls from attributes
        Frontend->>Frontend: Render users table + search + filters
        Frontend-->>Admin: Display user list with search/filter UI
    end
    
    alt Admin performs general search
        Admin->>Frontend: Type in search box (e.g., "john")
        Frontend->>Frontend: Update search query
        Frontend->>Backend: GET /api/users/?pagination=...filters:{"search":"john"}
        Backend-->>Frontend: Filtered users list
        Frontend-->>Admin: Display matching users
    end
    
    alt Admin applies field filter
        Admin->>Frontend: Select filter field (e.g., "Privilege")
        Frontend->>Frontend: Show filter options from attribute metadata
        Admin->>Frontend: Select filter value (e.g., "admin")
        Frontend->>Frontend: Update filter parameters
        Frontend->>Backend: GET /api/users/?pagination=...filters:{"privilege":"admin"}
        Backend-->>Frontend: Filtered users list
        Frontend-->>Admin: Display filtered users
    end
    
    alt Admin combines search + filter + sort
        Admin->>Frontend: Apply search + filter + sort
        Frontend->>Frontend: Combine all parameters
        Frontend->>Backend: GET /api/users/?pagination=...filters:{"search":"john","privilege":"admin"}...sort:desc
        Backend-->>Frontend: Filtered, sorted users list
        Frontend-->>Admin: Display results
    end
    
    Admin->>Frontend: Click column header (e.g., "Email")
    Frontend->>Frontend: Update sort parameters
    Frontend->>Backend: GET /api/users/?pagination=...sort:desc
    Backend-->>Frontend: Sorted users list
    Frontend-->>Admin: Display sorted users
    
    Admin->>Frontend: Click user row
    Frontend->>Frontend: Navigate to /users/userId
    Frontend-->>Admin: Show user detail page
```

---

## Customer Journey 2: Viewing User Details

### User Goal
"As an administrator, I want to see everything about a specific user—their account information, privilege level, and status."

### User Story
As an administrator, I want to open a user and see their complete information, including username, email, full name, language preference, enabled status, privilege level, authentication authority, and mandate association.

### User Story Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: Click user from list
    Frontend->>Backend: GET /api/users/userId
    Backend-->>Frontend: User object
    
    Frontend->>Backend: GET /api/attributes/User
    Backend-->>Frontend: Field definitions
    
    Frontend->>Frontend: Generate UI from metadata
    Frontend->>Frontend: Render user info section
    Frontend->>Frontend: Separate editable vs read-only fields
    Frontend-->>Admin: Display complete user view
    
    alt User has editable fields and admin has permission
        Frontend->>Frontend: Show "Edit User" button
    end
    
    alt Admin has permission
        Frontend->>Frontend: Show "Reset Password" button
        Frontend->>Frontend: Show "Revoke Sessions" button
        Frontend->>Frontend: Show "Delete User" button
    end
    
    alt Admin clicks "Revoke Sessions"
        Admin->>Frontend: Click "Revoke Sessions" button
        Frontend->>Frontend: Show revocation dialog
        Admin->>Frontend: Select authority filter (optional)
        Admin->>Frontend: Enter reason (optional)
        Admin->>Frontend: Click "Revoke"
        Frontend->>Frontend: Optimistic update: Show loading state
        Frontend->>Backend: POST /api/admin/tokens/revoke/user
        alt Success
            Backend-->>Frontend: {"revoked": count}
            Frontend->>Frontend: Keep optimistic update
            Frontend->>Backend: GET /api/users/userId (refetch)
            Backend-->>Frontend: Updated user object
            Frontend->>Frontend: Update UI with fresh data
            Frontend-->>Admin: Show success message
        else Error (403/400/500)
            Backend-->>Frontend: Error response
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>Admin: Show error message
        end
    end
    
    alt Admin clicks "Reset Password"
        Admin->>Frontend: Click "Reset Password" button
        Frontend->>Frontend: Show password reset dialog
        Admin->>Frontend: Enter new password
        Admin->>Frontend: Confirm password
        Admin->>Frontend: Click "Reset"
        Frontend->>Frontend: Optimistic update: Show loading state
        Frontend->>Backend: POST /api/users/userId/reset-password
        alt Success
            Backend-->>Frontend: Success response
            Frontend->>Frontend: Keep optimistic update
            Frontend->>Backend: GET /api/users/userId (refetch)
            Backend-->>Frontend: Updated user object
            Frontend->>Frontend: Update UI with fresh data
            Frontend-->>Admin: Show success message
        else Error (403/400/500)
            Backend-->>Frontend: Error response
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>Admin: Show error message
        end
    end
    
    alt Admin clicks "Delete User"
        Admin->>Frontend: Click "Delete User" button
        Frontend->>Backend: GET /api/users/userId
        Backend-->>Frontend: User data (for name)
        Frontend->>Frontend: Show confirmation dialog
        Admin->>Frontend: Confirm deletion
        Frontend->>Frontend: Optimistic update: Remove user from UI
        Frontend->>Backend: DELETE /api/users/userId
        alt Success
            Backend-->>Frontend: Success response
            Frontend->>Frontend: Keep optimistic update
            Frontend->>Frontend: Navigate to /users
            Frontend-->>Admin: Show success message
        else Error (403/404/500)
            Backend-->>Frontend: Error response
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>Admin: Show error message
        end
    end
```


## Customer Journey 3: Creating New Users

### User Goal
"As an administrator, I want to create new users for my mandate."

### User Story
As an administrator, I want to create a new user by filling out a form with their username, email, full name, language preference, privilege level, and initial password. The form should validate all required fields and show clear error messages.

### User Story Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: Click "Create User" button
    Frontend->>Frontend: Navigate to /users/create
    
    Frontend->>Backend: GET /api/attributes/User
    Backend-->>Frontend: Field definitions (editable fields)
    
    Frontend->>Frontend: Filter editable fields
    Frontend->>Frontend: Generate form from attributes
    Frontend->>Frontend: Add password field (special case)
    Frontend-->>Admin: Display create user form
    
    Admin->>Frontend: Fill in form fields
    Admin->>Frontend: Enter password
    Admin->>Frontend: Click "Create"
    
    Frontend->>Frontend: Validate form (required fields, types, email format)
    alt Validation fails
        Frontend-->>Admin: Show validation errors
    else Validation passes
        Frontend->>Backend: POST /api/users + form data + password
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend-->>Admin: Show permission error
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request + error details
            Frontend-->>Admin: Show backend validation errors
        else Success (200)
            Backend-->>Frontend: Created user object
            Frontend->>Frontend: Navigate to user detail page
            Frontend-->>Admin: Show created user
        end
    end
```

## Customer Journey 4: Editing User Properties

### User Goal
"As an administrator, I want to change user settings like their name, email, privilege level, or enabled status."

### User Story
As an administrator, I want to edit a user'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 Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: Click "Edit" button
    Frontend->>Frontend: Navigate to /users/id/edit
    
    Frontend->>Backend: GET /api/users/userId
    Backend-->>Frontend: Current user data
    
    Frontend->>Backend: GET /api/attributes/User
    Backend-->>Frontend: Field definitions (editable fields)
    
    Frontend->>Frontend: Filter editable fields
    Frontend->>Frontend: Generate form from attributes
    Frontend->>Frontend: Pre-populate form with user data
    Frontend-->>Admin: Display edit form
    
    Admin->>Frontend: Modify form fields
    Admin->>Frontend: Click "Save"
    
    Frontend->>Frontend: Validate form (required fields, types)
    alt Validation fails
        Frontend-->>Admin: Show validation errors
    else Validation passes
        Frontend->>Frontend: Optimistic update: Apply changes to UI immediately
        Frontend->>Backend: PUT /api/users/userId + form data
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>Admin: Show permission error
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request + error details
            Frontend->>Frontend: Revert optimistic update
            Frontend-->>Admin: Show backend validation errors
        else Success (200)
            Backend-->>Frontend: Updated user
            Frontend->>Frontend: Keep optimistic update (or refresh from response)
            Frontend->>Frontend: Navigate to detail page
            Frontend-->>Admin: Show updated user
        end
    end
```

---

## Customer Journey 5: Enabling and Disabling Users

### User Goal
"As an administrator, I want to quickly enable or disable users directly from the user list without navigating to their detail page."

### User Story
As an administrator, I want to toggle a user's enabled status directly in the user list table. When I click the toggle, it should immediately update the user's status in the backend with an optimistic update, so the UI feels responsive and confident.

### User Story Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: View user list table
    Frontend->>Backend: GET /api/users/?pagination=...
    Backend-->>Frontend: Paginated users list
    Frontend->>Frontend: Render table with enabled toggle column
    Frontend-->>Admin: Display user list with enabled toggles
    
    Admin->>Frontend: Click enabled toggle for user
    Frontend->>Frontend: Optimistic update: Toggle switch immediately<br/>(enabled: true → false or false → true)
    Frontend->>Backend: PUT /api/users/userId + {enabled: newValue}
    alt Success (200)
        Backend->>Backend: Update user enabled status
        Backend-->>Frontend: Updated user object
        Frontend->>Frontend: Keep optimistic update (toggle already changed)
        Frontend->>Backend: GET /api/users/?pagination=... (refetch list)
        Backend-->>Frontend: Updated users list
        Frontend->>Frontend: Update table with fresh data
        Frontend-->>Admin: Show subtle success indicator (optional)
    else Error (403/400/404/500)
        Backend-->>Frontend: Error response
        Frontend->>Frontend: Revert optimistic update: Toggle back to original state
        Frontend-->>Admin: Show error message
    end
```

## Customer Journey 6: Resetting User Passwords

### User Goal
"As an administrator, I want to reset a user's password when they forget it or need a new one."

### User Story
As an administrator, I want to reset a user's password by entering a new password. The system should validate password strength and automatically revoke all existing tokens for security.

### User Story Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: Click "Reset Password" button
    Frontend->>Frontend: Show password reset dialog
    
    Admin->>Frontend: Enter new password
    Admin->>Frontend: Confirm new password
    Admin->>Frontend: Click "Reset"
    
    Frontend->>Frontend: Validate password (min 8 characters)
    Frontend->>Frontend: Validate passwords match
    alt Validation fails
        Frontend-->>Admin: Show validation errors
    else Validation passes
        Frontend->>Backend: POST /api/users/userId/reset-password + newPassword
        alt Permission denied (403)
            Backend-->>Frontend: 403 Forbidden
            Frontend-->>Admin: Show permission error
        else Validation error (400)
            Backend-->>Frontend: 400 Bad Request (password too short)
            Frontend-->>Admin: Show validation error
        else Success (200)
            Backend->>Backend: Reset password
            Backend->>Backend: Revoke all user tokens
            Backend-->>Frontend: Success response
            Frontend-->>Admin: Show success message
        end
    end
```

### Frontend Requirements

> **📋 Complete frontend requirements for this journey are documented in [User Page Requirements](./user-page-requirements.md#customer-journey-6-resetting-user-passwords)**

The frontend must implement a password reset dialog with password strength validation. This is an admin-only action.

```typescript
const handleResetPassword = async (userId: string, newPassword: string) => {
  // Validate password strength
  if (newPassword.length < 8) {
    showError('Password must be at least 8 characters long');
    return;
  }
  
  const response = await fetch(`/api/users/${userId}/reset-password`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ newPassword })
  });
  
  if (response.ok) {
    showSuccess('Password reset successfully. All user sessions have been revoked.');
  } else {
    const error = await response.json();
    showError(error.detail || 'Failed to reset password');
  }
};
```

---

## Customer Journey 7: Revoking User Sessions

### User Goal
"As an administrator, I want to revoke all active sessions for a user to force them to log in again."

### User Story
As an administrator, I want to revoke all active tokens/sessions for a user, optionally filtered by authentication authority (local, Google, Microsoft). This is useful for security purposes, such as when a user's account may have been compromised or when they need to be logged out of all devices.

### User Story Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: Click "Revoke Sessions" button
    Frontend->>Frontend: Show session revocation dialog
    
    Admin->>Frontend: Optionally select authority filter (local/Google/Microsoft)
    Admin->>Frontend: Optionally enter reason
    Admin->>Frontend: Click "Revoke Sessions"
    
    Frontend->>Backend: POST /api/admin/tokens/revoke/user + {userId, authority?, reason?}
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend-->>Admin: Show permission error
    else Success (200)
        Backend->>Backend: Revoke all active tokens for user
        Backend-->>Frontend: {"revoked": count}
        Frontend-->>Admin: Show success message with count
    end
```

---

## Customer Journey 8: Deleting Users

### User Goal
"As an administrator, I want to delete users that are no longer needed."

### User Story
As an administrator, I want to delete users with a clear confirmation to prevent accidental deletion.

### User Story Flow

```mermaid
sequenceDiagram
    participant Admin
    participant Frontend
    participant Backend
    
    Admin->>Frontend: Click "Delete" button
    Frontend->>Backend: GET /api/users/userId
    Backend-->>Frontend: User data (for name)
    Frontend->>Frontend: Show confirmation dialog<br/>"Delete 'User Name'?"
    Admin->>Frontend: Cancel deletion
    Frontend-->>Admin: Dialog closed, no action
    
    Admin->>Frontend: Click "Delete" button again
    Frontend->>Backend: GET /api/users/userId
    Backend-->>Frontend: User data
    Frontend->>Frontend: Show confirmation dialog
    Admin->>Frontend: Confirm deletion
    Frontend->>Frontend: Optimistic update: Remove user from UI immediately
    Frontend->>Backend: DELETE /api/users/userId
    
    alt Permission denied (403)
        Backend-->>Frontend: 403 Forbidden
        Frontend->>Frontend: Revert optimistic update: Restore user in UI
        Frontend-->>Admin: Show permission error
    else Not found (404)
        Backend-->>Frontend: 404 Not Found
        Frontend->>Frontend: Revert optimistic update: Restore user in UI
        Frontend-->>Admin: Show not found error
    else Success (200)
        Backend-->>Frontend: Success response
        Frontend->>Frontend: Keep optimistic update (user already removed)
        Frontend->>Frontend: Show success message
        Frontend->>Frontend: Navigate to /users (if on detail page)
        Frontend-->>Admin: Display user list (without deleted user)
    end
```