[codex] Improve UI architecture guardrails

ui/agents/patterns.md

@@ -96,7 +96,7 @@ All user-facing API feedback flows through `MutationCache` / `QueryCache` in `sr
 
 Behavior:
 
-- `MutationCache.onSuccess` — shows a green notification **only if `meta.successMessage` is provided**, then auto-invalidates `meta.invalidates` query keys.
+- `MutationCache.onSuccess` — shows a notification **only if `meta.successMessage` is provided**, then auto-invalidates `meta.invalidates` query keys. `successMessage` and `successColor` may be resolver functions when the message/color depends on the mutation result.
 - `MutationCache.onError` — shows a red notification with `meta.errorMessage` as the title + the error detail.
 - `QueryCache.onError` — shows a red notification **only** for background refetch failures (query that previously had data). Initial load failures surface through route `errorComponent`.
 - Both caches respect `meta.skipNotification` for background/silent operations.

ui/eslint.config.js

@@ -256,4 +256,52 @@ export default defineConfig(
       'jsonc/no-comments': 'off',
     },
   },
+
+  // =============================================
+  // Project architecture guardrails
+  // =============================================
+  {
+    files: ['src/shared/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['@/features/*'],
+              message: 'Shared code must not depend on feature modules. Move the component into features or extract a shared primitive.',
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    files: ['src/features/**/*.{ts,tsx}', 'src/routes/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        {
+          paths: [
+            {
+              name: '@mantine/notifications',
+              message: 'Use NotificationMeta on query/mutation options; global QueryCache/MutationCache owns notifications.',
+            },
+            {
+              name: 'mantine-react-table',
+              importNames: ['MantineReactTable'],
+              message: 'Use the shared DataTable wrapper instead of rendering MantineReactTable directly.',
+            },
+          ],
+        },
+      ],
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'Property[key.name=\'queryKey\'][value.type=\'ArrayExpression\']',
+          message: 'Use a feature query key factory and queryOptions() instead of inline queryKey arrays.',
+        },
+      ],
+    },
+  },
 )

ui/src/features/admin/registries/registries.query.ts

@@ -14,6 +14,7 @@ export const adminRegistryKeys = {
   all: ['admin', 'registries'] as const,
   lists: () => [...adminRegistryKeys.all, 'list'] as const,
   list: (search: RegistriesSearch) => [...adminRegistryKeys.lists(), search] as const,
+  allRegistries: () => [...adminRegistryKeys.lists(), 'all'] as const,
 }
 
 export function registriesQueryOptions(search: RegistriesSearch) {
@@ -34,6 +35,23 @@ export function registriesQueryOptions(search: RegistriesSearch) {
   })
 }
 
+export function allRegistriesQueryOptions() {
+  return queryOptions({
+    queryKey: adminRegistryKeys.allRegistries(),
+    queryFn: async () => {
+      const response = await Registries.ListRegistries({
+        page: 1,
+        pageSize: -1,
+      })
+
+      return {
+        registries: response.registries ?? [],
+        pagination: response.pagination,
+      }
+    },
+  })
+}
+
 // -- Custom hook --
 
 export function useRegistries(search: RegistriesSearch) {

ui/src/features/admin/replications/components/ReplicationFormModal.tsx

@@ -23,7 +23,7 @@ import { useMutation, useQuery } from '@tanstack/react-query'
 import { useMemo } from 'react'
 import { useTranslation } from 'react-i18next'
 
-import { registriesQueryOptions } from '@/features/admin/registries/registries.query'
+import { allRegistriesQueryOptions } from '@/features/admin/registries/registries.query'
 import { FieldHintLabel } from '@/shared/components/FieldHintLabel'
 import { ModalWrapper } from '@/shared/components/ModalWrapper'
 import { useForm } from '@/shared/hooks/useForm'
@@ -189,10 +189,7 @@ export function ReplicationFormModal({
   const createMutation = useMutation(createReplicationMutationOptions())
   const updateMutation = useMutation(updateReplicationMutationOptions())
   const registriesQuery = useQuery({
-    ...registriesQueryOptions({
-      page: 1,
-      query: '',
-    }),
+    ...allRegistriesQueryOptions(),
     enabled: opened,
   })
 

ui/src/features/admin/users/components/BatchDeleteUsersModal.tsx

@@ -4,7 +4,6 @@ import {
   Stack,
   Text,
 } from '@mantine/core'
-import { notifications } from '@mantine/notifications'
 import { useMutation } from '@tanstack/react-query'
 import { useTranslation } from 'react-i18next'
 
@@ -33,22 +32,7 @@ export function BatchDeleteUsersModal({
   const usernames = users.map(getUserDisplayName).join(', ')
 
   const handleDelete = async () => {
-    const res = await mutation.mutateAsync(users)
-
-    if (res && res.partial) {
-      notifications.show({
-        color: 'yellow',
-        message: t('routes.admin.users.notifications.batchDeletePartialError', {
-          successCount: res.successCount,
-          failureCount: res.failureCount,
-        }),
-      })
-    } else {
-      notifications.show({
-        color: 'green',
-        message: t('routes.admin.users.notifications.batchDeleteSuccess'),
-      })
-    }
+    await mutation.mutateAsync(users)
     onSuccess()
     onClose()
   }

ui/src/features/admin/users/users.mutation.ts

@@ -24,6 +24,13 @@ function requireUserId(id?: number) {
 
 type UserSysAdminMutationInput = Pick<SetUserSysAdminRequest, 'id'>
 
+interface BatchDeleteUsersResult {
+  partial: boolean
+  successCount: number
+  failureCount: number
+  failed: PromiseRejectedResult[]
+}
+
 function userSysAdminMutationOptions({
   sysadminFlag,
   successMessage,
@@ -108,7 +115,7 @@ export function deleteUserMutationOptions() {
 
 export function batchDeleteUsersMutationOptions() {
   return mutationOptions({
-    mutationFn: async (users: readonly User[]) => {
+    mutationFn: async (users: readonly User[]): Promise<BatchDeleteUsersResult> => {
       if (users.length === 0) {
         throw new Error(i18n.t('routes.admin.users.errors.noUsersSelected'))
       }
@@ -146,6 +153,17 @@ export function batchDeleteUsersMutationOptions() {
       }
     },
     meta: {
+      successMessage: (data) => {
+        const result = data as BatchDeleteUsersResult
+
+        return result.partial
+          ? i18n.t('routes.admin.users.notifications.batchDeletePartialError', {
+              successCount: result.successCount,
+              failureCount: result.failureCount,
+            })
+          : i18n.t('routes.admin.users.notifications.batchDeleteSuccess')
+      },
+      successColor: data => ((data as BatchDeleteUsersResult).partial ? 'yellow' : 'green'),
       errorMessage: i18n.t('routes.admin.users.notifications.batchDeleteError'),
       invalidates: [adminUserKeys.lists()],
     } satisfies NotificationMeta,

ui/src/features/admin/users/users.query.ts

@@ -14,6 +14,7 @@ export const adminUserKeys = {
   all: ['admin', 'users'] as const,
   lists: () => [...adminUserKeys.all, 'list'] as const,
   list: (search: UsersSearch) => [...adminUserKeys.lists(), search] as const,
+  allUsers: () => [...adminUserKeys.lists(), 'all'] as const,
 }
 
 export function usersQueryOptions(search: UsersSearch) {
@@ -34,6 +35,23 @@ export function usersQueryOptions(search: UsersSearch) {
   })
 }
 
+export function allUsersQueryOptions() {
+  return queryOptions({
+    queryKey: adminUserKeys.allUsers(),
+    queryFn: async () => {
+      const response = await Users.ListUsers({
+        page: 1,
+        pageSize: -1,
+      })
+
+      return {
+        users: response.users ?? [],
+        pagination: response.pagination,
+      }
+    },
+  })
+}
+
 // -- Custom hook --
 
 export function useUsers(search: UsersSearch) {

ui/src/features/login/login.mutation.ts

@@ -0,0 +1,24 @@
+import { Login, type LoginRequest } from '@matrixhub/api-ts/v1alpha1/login.pb'
+import { mutationOptions } from '@tanstack/react-query'
+
+import i18n from '@/i18n'
+
+import type { NotificationMeta } from '@/types/tanstack-query'
+
+export function loginMutationOptions() {
+  return mutationOptions({
+    mutationFn: (values: LoginRequest) => Login.Login(values),
+    meta: {
+      errorMessage: i18n.t('login.error'),
+    } satisfies NotificationMeta,
+  })
+}
+
+export function logoutMutationOptions() {
+  return mutationOptions({
+    mutationFn: () => Login.Logout({}),
+    meta: {
+      errorMessage: i18n.t('login.logoutError'),
+    } satisfies NotificationMeta,
+  })
+}

ui/src/features/login/pages/LoginPage.tsx

@@ -1,12 +1,12 @@
 import {
   Button, Checkbox, Flex, Group, PasswordInput, ScrollArea, Stack, Text, TextInput, rem,
 } from '@mantine/core'
-import { Login, type LoginRequest } from '@matrixhub/api-ts/v1alpha1/login.pb'
 import { useMutation } from '@tanstack/react-query'
 import { useNavigate } from '@tanstack/react-router'
 import { useTranslation } from 'react-i18next'
 
 import LogoIcon from '@/assets/svgs/logo.svg?react'
+import { loginMutationOptions } from '@/features/login/login.mutation'
 import { LanguageSwitcher } from '@/shared/components/LanguageSwitcher'
 import { useForm } from '@/shared/hooks/useForm'
 
@@ -17,7 +17,7 @@ export function LoginPage() {
   const {
     mutate: handleLogin, isPending: isLoggingIn,
   } = useMutation({
-    mutationFn: (values: LoginRequest) => Login.Login(values),
+    ...loginMutationOptions(),
     onSuccess: () => {
       navigate({ to: '/' })
     },
@@ -75,6 +75,7 @@ export function LoginPage() {
                 size="md"
                 name={field.name}
                 value={field.state.value}
+                onBlur={field.handleBlur}
                 onChange={e => field.handleChange(e.target.value)}
               />
             )}
@@ -91,6 +92,7 @@ export function LoginPage() {
                 size="md"
                 name={field.name}
                 value={field.state.value}
+                onBlur={field.handleBlur}
                 onChange={e => field.handleChange(e.target.value)}
               />
             )}
@@ -101,6 +103,7 @@ export function LoginPage() {
               <Checkbox
                 name={field.name}
                 checked={field.state.value}
+                onBlur={field.handleBlur}
                 onChange={e => field.handleChange(e.target.checked)}
                 label={t('login.rememberMe')}
                 style={{ alignSelf: 'flex-start' }}

ui/src/features/models/components/AllModelList.tsx

@@ -11,9 +11,9 @@ import { getRouteApi } from '@tanstack/react-router'
 import { startTransition } from 'react'
 import { useTranslation } from 'react-i18next'
 
+import { ModelCard } from '@/features/models/components/ModelCard'
 import { catalogModelsQueryOptions } from '@/features/models/models.query'
 import { Pagination } from '@/shared/components/Pagination'
-import { ModelCard } from '@/shared/components/resource-card/ModelCard.tsx'
 import { ResourceCardGrid } from '@/shared/components/ResourceCardGrid'
 import { SearchToolbar } from '@/shared/components/SearchToolbar'
 import {

ui/src/features/models/components/HotModelList.tsx

@@ -7,8 +7,8 @@ import { useQuery } from '@tanstack/react-query'
 import { getRouteApi } from '@tanstack/react-router'
 import { useTranslation } from 'react-i18next'
 
+import { ModelCard } from '@/features/models/components/ModelCard'
 import { catalogModelsQueryOptions } from '@/features/models/models.query.ts'
-import { ModelCard } from '@/shared/components/resource-card/ModelCard.tsx'
 import { ResourceCardGrid } from '@/shared/components/ResourceCardGrid'
 
 const { useSearch } = getRouteApi('/(auth)/(app)/models/')

ui/src/features/profile/components/AccessTokenTable.tsx

@@ -5,14 +5,12 @@ import {
   Text,
 } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
-import {
-  CurrentUser, AccessTokenStatus, type AccessToken,
-} from '@matrixhub/api-ts/v1alpha1/current_user.pb'
+import { AccessTokenStatus, type AccessToken } from '@matrixhub/api-ts/v1alpha1/current_user.pb'
 import { useMutation } from '@tanstack/react-query'
 import { useState } from 'react'
 import { useTranslation } from 'react-i18next'
 
-import { profileKeys } from '@/features/profile/profile.query'
+import { deleteAccessTokenMutationOptions } from '@/features/profile/profile.mutation'
 import { formatExpiredAt } from '@/features/profile/profile.utils.ts'
 import { DataTable, type DataTableRowActionsProps } from '@/shared/components/DataTable'
 import { ModalWrapper } from '@/shared/components/ModalWrapper'
@@ -76,11 +74,7 @@ export function AccessTokenTable({ tokens }: AccessTokenTableProps) {
   const {
     mutate: deleteToken, isPending: isDeleting,
   } = useMutation({
-    mutationFn: () => CurrentUser.DeleteAccessToken({ id: deletingToken?.id }),
-    meta: {
-      successMessage: t('profile.tokenDeleted'),
-      invalidates: [profileKeys.accessTokens],
-    },
+    ...deleteAccessTokenMutationOptions(),
     onSuccess: () => {
       closeDelete()
       setDeletingToken(null)
@@ -97,6 +91,14 @@ export function AccessTokenTable({ tokens }: AccessTokenTableProps) {
     setDeletingToken(null)
   }
 
+  const handleDeleteConfirm = () => {
+    if (deletingToken?.id == null) {
+      return
+    }
+
+    deleteToken(deletingToken.id)
+  }
+
   const columns: MRT_ColumnDef<AccessToken>[] = [
     {
       accessorKey: 'name',
@@ -136,7 +138,7 @@ export function AccessTokenTable({ tokens }: AccessTokenTableProps) {
         title={t('profile.deleteToken')}
         opened={deleteOpened}
         onClose={handleDeleteClose}
-        onConfirm={() => deleteToken()}
+        onConfirm={handleDeleteConfirm}
         confirmLoading={isDeleting}
       >
         <Text size="sm">

ui/src/features/profile/components/CreateSshKeyModal.tsx

@@ -99,6 +99,7 @@ export function CreateSshKeyModal({
           <ExpireAtField
             value={field.state.value}
             onChange={field.handleChange}
+            onBlur={field.handleBlur}
             error={fieldError(field)}
           />
         )}

ui/src/features/profile/components/ExpireAtField.tsx

@@ -11,12 +11,14 @@ const defaultExpireAt = () => dayjs().add(1, 'day').format('YYYY-MM-DD')
 interface ExpireAtFieldProps {
   value: string
   onChange: (value: string) => void
+  onBlur?: () => void
   error?: string
 }
 
 export function ExpireAtField({
   value,
   onChange,
+  onBlur,
   error,
 }: ExpireAtFieldProps) {
   const { t } = useTranslation()
@@ -59,6 +61,7 @@ export function ExpireAtField({
           highlightToday
           required
           onChange={next => onChange(next ?? '')}
+          onBlur={onBlur}
           error={error}
         />
       )}