Administrator User Operations

Administrator user operations are managed through a dedicated interface in the frontend, restricted to users with superuser privileges. This system provides full CRUD (Create, Read, Update, Delete) capabilities, allowing administrators to manage account access, roles, and status across the platform.

The implementation relies on the UsersService SDK for API communication and a set of React components in frontend/src/components/Admin for the user interface.

User Data Representation

The admin interface uses the UserTableData type (defined in frontend/src/components/Admin/columns.tsx) to represent users in the management table. This type extends the standard UserPublic model with an additional flag to identify the currently logged-in administrator:

type UserTableData = UserPublic & {
  isCurrentUser: boolean
}

This flag is used to prevent administrators from performing destructive actions on their own accounts through the management table.

Creating New Users

New users are added via the AddUser component (frontend/src/components/Admin/AddUser.tsx). This component uses a Dialog containing a form validated by a Zod schema.

Validation and Submission

The formSchema enforces several rules for new accounts:

• Email: Must be a valid email format.
• Password: Minimum of 8 characters and must match the confirm_password field.
• Roles: Administrators can explicitly set is_superuser and is_active status upon creation.

The submission is handled by a TanStack Query mutation that calls UsersService.createUser:

const mutation = useMutation({
  mutationFn: (data: UserCreate) =>
    UsersService.createUser({ requestBody: data }),
  onSuccess: () => {
    showSuccessToast("User created successfully")
    form.reset()
    setIsOpen(false)
  },
  onError: handleError.bind(showErrorToast),
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ["users"] })
  },
})

Updating User Accounts

The EditUser component (frontend/src/components/Admin/EditUser.tsx) allows administrators to modify existing user details. It pre-populates the form with the user's current data.

Optional Password Updates

A key feature of the EditUser implementation is how it handles passwords. The password field is optional; if left blank, the existing password remains unchanged. The onSubmit handler specifically strips the password from the request if it hasn't been modified:

const onSubmit = (data: FormData) => {
  // exclude confirm_password from submission data and remove password if empty
  const { confirm_password: _, ...submitData } = data
  if (!submitData.password) {
    delete submitData.password
  }
  mutation.mutate(submitData)
}

The update is performed via UsersService.updateUser, which targets the specific user by their ID.

Deleting Users

The DeleteUser component (frontend/src/components/Admin/DeleteUser.tsx) provides a destructive action to remove a user from the system.

Cascading Deletion

The interface includes a critical warning: "All items associated with this user will also be permanently deleted." This reflects the backend's cascading delete behavior. The operation is performed using UsersService.deleteUser:

const deleteUser = async (id: string) => {
  await UsersService.deleteUser({ userId: id })
}

const mutation = useMutation({
  mutationFn: deleteUser,
  onSuccess: () => {
    showSuccessToast("The user was deleted successfully")
    setIsOpen(false)
    onSuccess()
  },
  // ...
})

Safety Mechanisms

To prevent accidental lockout or system instability, the UserActionsMenu (frontend/src/components/Admin/UserActionsMenu.tsx) contains logic to prevent an administrator from editing or deleting their own account.

The component checks the ID of the user being rendered against the currentUser from the useAuth hook. If they match, the actions menu is not rendered:

export const UserActionsMenu = ({ user }: UserActionsMenuProps) => {
  const [open, setOpen] = useState(false)
  const { user: currentUser } = useAuth()

  // Prevent self-modification
  if (user.id === currentUser?.id) {
    return null
  }

  return (
    <DropdownMenu open={open} onOpenChange={setOpen}>
      {/* ... EditUser and DeleteUser components ... */}
    </DropdownMenu>
  )
}

This ensures that an admin must use the standard "Settings" or "Profile" sections to manage their own account, preventing them from accidentally revoking their own superuser status or deleting themselves via the administrative table.