# frontend/src/hooks
dir: frontend/src/hooks

index: frontend/src/hooks/.pi-map.index.md

## role
Centralized React custom hooks package providing data-fetching, caching, and mutation logic via TanStack Query for all feature domains across the application.
## files
- useBackups.ts | Provides React Query custom hooks for fetching and managing backup-related data including jobs, runs, alerts, and dashboard metrics with automatic refetching. | exp: func:useBackupJobs(), call:useQuery, func:useBackupJob(jobId: string), call:useQuery, call:fetchBackupJob, func:useBackupRuns(jobId: string, status: string), call:useQuery, call:fetchBackupRuns, func:useBackupAlerts(jobId: string, acknowledged: boolean, severity: string), call:useQuery, call:fetchBackupAlerts, func:useAcknowledgeAlert(), call:useQueryClient, call:useMutation, call:queryClient.invalidateQueries, func:useBackupDashboard(), call:useQuery | dep: @tanstack/react-query, ../api/backups
- useDashboard.ts | Provides React Query custom hooks for fetching and mutating dashboard data including counts, libraries, activity, and shortcuts. | exp: useNowPlaying, func:useCounts(jellyfinServiceId: string), call:useQuery, call:fetchCounts, func:useLibraries(jellyfinServiceId: string), call:useQuery, call:fetchLibraries, func:useActivity(jellyfinServiceId: string), call:useQuery, call:fetchActivity, func:useDashboardShortcuts(), call:useQuery, func:useSaveDashboardShortcut(), call:useQueryClient, call:useMutation, call:saveDashboardShortcut, call:queryClient.invalidateQueries, func:useDeleteDashboardShortcut(), call:useQueryClient, call:useMutation, call:deleteDashboardShortcut, call:queryClient.invalidateQueries | dep: @tanstack/react-query, ../api/client, ../types
- useFiles.ts | Custom React hooks for file operations and job management using TanStack Query for data fetching, caching, and mutations. | exp: func:useDirectoryListing(path: string, machineId: string), call:useQuery, call:fetchDirectoryListing, func:useFfprobe(path: string, enabled, machineId: string), call:useQuery, call:fetchFfprobe, func:useStat(path: string, enabled, machineId: string), call:useQuery, call:fetchStat, func:useJobTemplates(), call:useQuery, func:useRunJob(machineId: string), call:useMutation, call:runJob | dep: @tanstack/react-query, ../api/client
- useMedia.ts | Custom React hooks for managing media status, querying media, and controlling index build operations using TanStack Query. | exp: func:useMediaStatus(jellyfinServiceId: string), call:useQuery, call:fetchMediaStatus, func:useMediaQuery(params: { libraries?: string; types?: string; search?: string; hdr_filter?: string; sort_key?: string; sort_order?: string; limit?: number; offset?: number; jellyfinServiceId?: string; enabled?: boolean; }), call:useQuery, call:queryMedia, func:useBuildIndex(jellyfinServiceId: string), call:useQueryClient, call:useMutation, call:buildMediaIndex, call:invalidateMedia, func:useStopBuildIndex(jellyfinServiceId: string), call:useQueryClient, call:useMutation, call:stopMediaIndexBuild, call:invalidateMedia, func:useForceStopBuildIndex(jellyfinServiceId: string), call:useQueryClient, call:useMutation, call:forceStopMediaIndexBuild, call:invalidateMedia | dep: @tanstack/react-query, ../api/client
- useObservability.ts | Custom React hooks for fetching and polling observability data (Alertmanager alerts/status, Grafana/Prometheus status, Prometheus targets, monitoring machines) via React Query. | exp: func:useAlertmanagerAlerts(), call:useQuery, func:useAlertmanagerStatus(), call:useQuery, func:useGrafanaStatus(), call:useQuery, func:usePrometheusStatus(), call:useQuery, func:usePrometheusTargets(), call:useQuery, func:useMonitoringMachines(), call:useQuery | dep: @tanstack/react-query, ../api/client
- usePersistentState.ts | React hook that synchronizes state with localStorage to persist UI state across browser sessions | exp: func:usePersistentState(key: string, initialValue: T | (() => T)), call:useCallback, call:window.localStorage.getItem, call:JSON.parse, call:useState, call:useEffect, call:window.localStorage.setItem, call:JSON.stringify | dep: react
- useSendUserMessage.ts | Custom React hook that sends a user message and invalidates the message queue cache on success | exp: func:useSendUserMessage(), call:useQueryClient, call:useMutation, call:queryClient.invalidateQueries | dep: @tanstack/react-query, ../api/client
- useServices.ts | Provides custom React hooks for fetching, creating, updating, and deleting service instances and types using React Query. | exp: func:useServiceTypes(), call:useQuery, func:useServiceInstances(serviceType: string), call:useQuery, call:fetchServiceInstances, func:useSaveServiceInstance(), call:useQueryClient, call:useMutation, call:updateServiceInstance, call:createServiceInstance, call:queryClient.invalidateQueries, func:useDeleteServiceInstance(), call:useQueryClient, call:useMutation, call:deleteServiceInstance, call:queryClient.invalidateQueries | dep: @tanstack/react-query, ../api/services, ../types
- useSettings.ts | Provides React Query custom hooks for managing application settings including monitoring machines, SSH keys, saved tasks, and local database reset operations. | exp: func:useMonitoringSettings(), call:useQuery, func:useSSHKeys(), call:useQuery, func:useGenerateSSHKey(), call:useMutation, call:generateSSHKey, func:useSaveSSHKey(), call:useQueryClient, call:useMutation, call:saveSSHKey, call:queryClient.invalidateQueries, func:useDeleteSSHKey(), call:useQueryClient, call:useMutation, call:deleteSSHKey, call:queryClient.invalidateQueries, func:useTasks(), call:useQuery, func:useTaskRuns(taskId: string), call:useQuery, call:fetchSavedTaskRuns, call:Boolean, func:useSaveTask(), call:useQueryClient, call:useMutation, call:saveTask, call:queryClient.invalidateQueries, func:useDeleteTask(), call:useQueryClient, call:useMutation, call:deleteTask, call:queryClient.invalidateQueries, func:useRunTask(), call:useQueryClient, call:useMutation, call:runTask, call:queryClient.invalidateQueries, func:useSaveMonitoringMachine(), call:useQueryClient, call:useMutation, call:saveMonitoringMachine, call:queryClient.invalidateQueries, func:useTestMonitoringMachineSSH(), call:useMutation, func:useDeleteMonitoringMachine(), call:useQueryClient, call:useMutation, call:deleteMonitoringMachine, call:queryClient.invalidateQueries, func:useResetLocalDatabase(), call:useQueryClient, call:useMutation, call:resetLocalDatabase, call:queryClient.invalidateQueries | dep: @tanstack/react-query, ../api/client, ../types
- useUserMessageQueueStatus.ts | Custom React hook that polls for user message queue status every 5 seconds using TanStack Query | exp: func:useUserMessageQueueStatus(), call:useQuery | dep: @tanstack/react-query, ../api/client
- useUsers.ts | Custom React hook that fetches and caches user directory data using TanStack Query with configurable Jellyfin service ID | exp: func:useUsers(jellyfinServiceId: string), call:useQuery, call:fetchUsers | dep: @tanstack/react-query, ../api/client, ../types
- useWidgets.ts | Custom React hooks for managing widget data fetching, caching, and mutations using TanStack Query. | exp: func:useWidgetInstances(), call:useQuery, func:useWidgetData(widgetId: string, refreshInterval: number), call:useQuery, call:fetchWidgetData, func:useSaveWidgetInstance(), call:useQueryClient, call:useMutation, call:updateWidgetInstance, call:createWidgetInstance, call:queryClient.invalidateQueries, func:useDeleteWidgetInstance(), call:useQueryClient, call:useMutation, call:deleteWidgetInstance, call:queryClient.invalidateQueries, func:useBuiltinWidgetKinds(), call:useQuery | dep: @tanstack/react-query, ../api/widgets, ../types
## arch
React Query (TanStack Query) pattern with domain-specific hook modules, leveraging automatic refetching, polling, and cache invalidation, supplemented by a localStorage-backed persistent state hook.
## tags
call:use, query, client, mutation, call:query, client.invalidate, queries, call:fetch
## symbols
- useBackupJobs
- useBackupJob
- useBackupRuns
- useBackupAlerts
- useAcknowledgeAlert
- useBackupDashboard
- useCounts
- useLibraries
## workflows
- change hooks behavior
  read: useBackups.ts, useDashboard.ts, useFiles.ts
## dirty
-
