From c630635cffc7b7aa56b018f83d8480d9100e2129 Mon Sep 17 00:00:00 2001
From: Randy Hammond <revtex@gmail.com>
Date: Sat, 25 Apr 2026 16:46:33 +0000
Subject: [PATCH] refactor(frontend): split hooks/ into shared, scanner, admin
 (Phase 5)

Phase 5 of the directory restructure plan. Pure file moves with
import-path updates and new barrel index files; no runtime behaviour
change.

Moves (15 files, all tracked as renames):
- hooks/{useAuthInit,useTheme,useTokenRefresh,useWebSocket}.* -> hooks/shared/
- hooks/{useScanner,useAudioPlayer,useTGSelectionSync,useActiveUnit}.ts -> hooks/scanner/
- hooks/{useAdminWebSocket,useAdminWsOps,useAdminActivity,useAdminLogs,useWsQuery}.ts -> hooks/admin/

Added barrel index.ts in each subfolder plus hooks/index.ts (root
safety net). All 31 @/hooks/* import sites across components, pages,
hooks, and tests have been updated to specific paths.

tsc --noEmit clean, 188/188 unit tests pass.
---
 CHANGELOG.md                                             | 7 +++++++
 frontend/src/components/admin/ActivityPanel.tsx          | 2 +-
 frontend/src/components/admin/AdminLayout.tsx            | 2 +-
 frontend/src/components/admin/ApiKeysPanel.test.tsx      | 2 +-
 frontend/src/components/admin/ApiKeysPanel.tsx           | 2 +-
 frontend/src/components/admin/DirMonitorPanel.tsx        | 2 +-
 frontend/src/components/admin/DownstreamsPanel.tsx       | 2 +-
 frontend/src/components/admin/GroupsTagsPanel.tsx        | 2 +-
 frontend/src/components/admin/LogsPanel.tsx              | 4 ++--
 frontend/src/components/admin/OptionsPanel.tsx           | 2 +-
 frontend/src/components/admin/RadioReferenceCard.tsx     | 2 +-
 frontend/src/components/admin/SharedLinksPanel.tsx       | 2 +-
 frontend/src/components/admin/SystemsPanel.test.tsx      | 2 +-
 frontend/src/components/admin/SystemsPanel.tsx           | 2 +-
 frontend/src/components/admin/ToolsPanel.tsx             | 2 +-
 frontend/src/components/admin/TranscriptionPanel.tsx     | 2 +-
 frontend/src/components/admin/UsersPanel.test.tsx        | 2 +-
 frontend/src/components/admin/UsersPanel.tsx             | 2 +-
 frontend/src/components/admin/WebhooksPanel.tsx          | 2 +-
 frontend/src/components/scanner/DisplayPanel.tsx         | 2 +-
 frontend/src/components/scanner/LEDPanel.test.tsx        | 2 +-
 frontend/src/components/scanner/LEDPanel.tsx             | 2 +-
 frontend/src/hooks/admin/index.ts                        | 5 +++++
 frontend/src/hooks/{ => admin}/useAdminActivity.ts       | 0
 frontend/src/hooks/{ => admin}/useAdminLogs.ts           | 0
 frontend/src/hooks/{ => admin}/useAdminWebSocket.ts      | 0
 frontend/src/hooks/{ => admin}/useAdminWsOps.ts          | 2 +-
 frontend/src/hooks/{ => admin}/useWsQuery.ts             | 0
 frontend/src/hooks/index.ts                              | 7 +++++++
 frontend/src/hooks/scanner/index.ts                      | 4 ++++
 frontend/src/hooks/{ => scanner}/useActiveUnit.ts        | 0
 frontend/src/hooks/{ => scanner}/useAudioPlayer.ts       | 0
 frontend/src/hooks/{ => scanner}/useScanner.ts           | 4 ++--
 frontend/src/hooks/{ => scanner}/useTGSelectionSync.ts   | 0
 frontend/src/hooks/shared/index.ts                       | 4 ++++
 frontend/src/hooks/{ => shared}/useAuthInit.test.tsx     | 2 +-
 frontend/src/hooks/{ => shared}/useAuthInit.ts           | 0
 frontend/src/hooks/{ => shared}/useTheme.ts              | 0
 frontend/src/hooks/{ => shared}/useTokenRefresh.test.tsx | 2 +-
 frontend/src/hooks/{ => shared}/useTokenRefresh.ts       | 0
 frontend/src/hooks/{ => shared}/useWebSocket.ts          | 0
 frontend/src/main.tsx                                    | 4 ++--
 frontend/src/pages/Scanner.tsx                           | 4 ++--
 43 files changed, 58 insertions(+), 31 deletions(-)
 create mode 100644 frontend/src/hooks/admin/index.ts
 rename frontend/src/hooks/{ => admin}/useAdminActivity.ts (100%)
 rename frontend/src/hooks/{ => admin}/useAdminLogs.ts (100%)
 rename frontend/src/hooks/{ => admin}/useAdminWebSocket.ts (100%)
 rename frontend/src/hooks/{ => admin}/useAdminWsOps.ts (99%)
 rename frontend/src/hooks/{ => admin}/useWsQuery.ts (100%)
 create mode 100644 frontend/src/hooks/index.ts
 create mode 100644 frontend/src/hooks/scanner/index.ts
 rename frontend/src/hooks/{ => scanner}/useActiveUnit.ts (100%)
 rename frontend/src/hooks/{ => scanner}/useAudioPlayer.ts (100%)
 rename frontend/src/hooks/{ => scanner}/useScanner.ts (95%)
 rename frontend/src/hooks/{ => scanner}/useTGSelectionSync.ts (100%)
 create mode 100644 frontend/src/hooks/shared/index.ts
 rename frontend/src/hooks/{ => shared}/useAuthInit.test.tsx (98%)
 rename frontend/src/hooks/{ => shared}/useAuthInit.ts (100%)
 rename frontend/src/hooks/{ => shared}/useTheme.ts (100%)
 rename frontend/src/hooks/{ => shared}/useTokenRefresh.test.tsx (98%)
 rename frontend/src/hooks/{ => shared}/useTokenRefresh.ts (100%)
 rename frontend/src/hooks/{ => shared}/useWebSocket.ts (100%)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d5ea226..401f0c3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,6 +41,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `client.test.ts`, `adminClient.ts`) and `services/audio/` (`player.ts`,
   `beep.ts`). All `@/services/*` imports across components and hooks have
   been updated to the new paths. No runtime behaviour change.
+- Frontend `hooks/` directory split into `hooks/shared/` (`useAuthInit`,
+  `useTheme`, `useTokenRefresh`, `useWebSocket`), `hooks/scanner/`
+  (`useScanner`, `useAudioPlayer`, `useTGSelectionSync`, `useActiveUnit`),
+  and `hooks/admin/` (`useAdminWebSocket`, `useAdminWsOps`,
+  `useAdminActivity`, `useAdminLogs`, `useWsQuery`), each with a barrel
+  `index.ts`. All call sites have been updated to the new specific paths.
+  No runtime behaviour change.
 
 ### Fixed
 
diff --git a/frontend/src/components/admin/ActivityPanel.tsx b/frontend/src/components/admin/ActivityPanel.tsx
index 7c7804b..99e17df 100644
--- a/frontend/src/components/admin/ActivityPanel.tsx
+++ b/frontend/src/components/admin/ActivityPanel.tsx
@@ -1,4 +1,4 @@
-import { useAdminActivity } from "@/hooks/useAdminActivity";
+import { useAdminActivity } from "@/hooks/admin/useAdminActivity";
 import type { ChartBucket } from "@/app/slices/activitySlice";
 import {
   Activity,
diff --git a/frontend/src/components/admin/AdminLayout.tsx b/frontend/src/components/admin/AdminLayout.tsx
index 0a7399f..eed4b99 100644
--- a/frontend/src/components/admin/AdminLayout.tsx
+++ b/frontend/src/components/admin/AdminLayout.tsx
@@ -36,7 +36,7 @@ import {
   clearCredentials,
   usePostLogoutMutation,
 } from "@/app/slices/authSlice";
-import { useAdminWebSocket } from "@/hooks/useAdminWebSocket";
+import { useAdminWebSocket } from "@/hooks/admin/useAdminWebSocket";
 import UsersPanel from "@/components/admin/UsersPanel";
 import SystemsPanel from "@/components/admin/SystemsPanel";
 import GroupsTagsPanel from "@/components/admin/GroupsTagsPanel";
diff --git a/frontend/src/components/admin/ApiKeysPanel.test.tsx b/frontend/src/components/admin/ApiKeysPanel.test.tsx
index e51f3e3..464e86a 100644
--- a/frontend/src/components/admin/ApiKeysPanel.test.tsx
+++ b/frontend/src/components/admin/ApiKeysPanel.test.tsx
@@ -60,7 +60,7 @@ const deleteApiKeyMutate = vi.fn((_arg: unknown) => ({
   unwrap: deleteApiKeyUnwrap,
 }));
 
-vi.mock("@/hooks/useAdminWsOps", () => ({
+vi.mock("@/hooks/admin/useAdminWsOps", () => ({
   useListApiKeysQuery: () => ({ data: mockKeys, isLoading: false }),
   useListSystemsQuery: () => ({ data: mockSystems, isLoading: false }),
   useGetConfigQuery: () => ({ data: { settings: [] }, isLoading: false }),
diff --git a/frontend/src/components/admin/ApiKeysPanel.tsx b/frontend/src/components/admin/ApiKeysPanel.tsx
index 40fb8e2..1a8fe8e 100644
--- a/frontend/src/components/admin/ApiKeysPanel.tsx
+++ b/frontend/src/components/admin/ApiKeysPanel.tsx
@@ -7,7 +7,7 @@ import {
   useDeleteApiKeyMutation,
   useListSystemsQuery,
   useGetConfigQuery,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { AdminApiKey } from "@/types";
 
 // ─── Form state ───
diff --git a/frontend/src/components/admin/DirMonitorPanel.tsx b/frontend/src/components/admin/DirMonitorPanel.tsx
index 786f6d5..45a6ef1 100644
--- a/frontend/src/components/admin/DirMonitorPanel.tsx
+++ b/frontend/src/components/admin/DirMonitorPanel.tsx
@@ -8,7 +8,7 @@ import {
   useDeleteDirMonitorMutation,
   useListSystemsQuery,
   useListTalkgroupsQuery,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { AdminDirMonitor } from "@/types";
 
 const DIRMONITOR_TYPES = [
diff --git a/frontend/src/components/admin/DownstreamsPanel.tsx b/frontend/src/components/admin/DownstreamsPanel.tsx
index 4d7157f..b3dc2b3 100644
--- a/frontend/src/components/admin/DownstreamsPanel.tsx
+++ b/frontend/src/components/admin/DownstreamsPanel.tsx
@@ -6,7 +6,7 @@ import {
   useUpdateDownstreamMutation,
   useDeleteDownstreamMutation,
   useListSystemsQuery,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { AdminDownstream } from "@/types";
 
 interface DownstreamFormState {
diff --git a/frontend/src/components/admin/GroupsTagsPanel.tsx b/frontend/src/components/admin/GroupsTagsPanel.tsx
index caf6af2..04e56e4 100644
--- a/frontend/src/components/admin/GroupsTagsPanel.tsx
+++ b/frontend/src/components/admin/GroupsTagsPanel.tsx
@@ -9,7 +9,7 @@ import {
   useCreateTagMutation,
   useUpdateTagMutation,
   useDeleteTagMutation,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { AdminGroup, AdminTag } from "@/types";
 
 // ─── Generic label CRUD table ───
diff --git a/frontend/src/components/admin/LogsPanel.tsx b/frontend/src/components/admin/LogsPanel.tsx
index d39fea7..14cdb70 100644
--- a/frontend/src/components/admin/LogsPanel.tsx
+++ b/frontend/src/components/admin/LogsPanel.tsx
@@ -9,8 +9,8 @@ import {
   X,
 } from "lucide-react";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { useUpdateConfigMutation } from "@/hooks/useAdminWsOps";
-import { useAdminLogs, useAdminLogLevel } from "@/hooks/useAdminLogs";
+import { useUpdateConfigMutation } from "@/hooks/admin/useAdminWsOps";
+import { useAdminLogs, useAdminLogLevel } from "@/hooks/admin/useAdminLogs";
 import type { AdminLog } from "@/types";
 
 // ─── Constants ──────────────────────────────────────────────
diff --git a/frontend/src/components/admin/OptionsPanel.tsx b/frontend/src/components/admin/OptionsPanel.tsx
index c2a1099..8093b1c 100644
--- a/frontend/src/components/admin/OptionsPanel.tsx
+++ b/frontend/src/components/admin/OptionsPanel.tsx
@@ -10,7 +10,7 @@ import {
 import {
   useGetConfigQuery,
   useUpdateConfigMutation,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import { useNavigationGuard } from "@/components/admin/NavigationGuardContext";
 import type { AdminSetting } from "@/types";
 
diff --git a/frontend/src/components/admin/RadioReferenceCard.tsx b/frontend/src/components/admin/RadioReferenceCard.tsx
index 2b502b5..da5ee78 100644
--- a/frontend/src/components/admin/RadioReferenceCard.tsx
+++ b/frontend/src/components/admin/RadioReferenceCard.tsx
@@ -1,7 +1,7 @@
 import { useState, useRef, useCallback } from "react";
 import { Upload, CheckCircle, XCircle, AlertTriangle } from "lucide-react";
 import { useRrPreviewCSVMutation } from "@/app/slices/adminSlice";
-import { useRrApplyMutation, useListSystemsQuery } from "@/hooks/useAdminWsOps";
+import { useRrApplyMutation, useListSystemsQuery } from "@/hooks/admin/useAdminWsOps";
 import type {
   RRPreviewResponse,
   RRPreviewRow,
diff --git a/frontend/src/components/admin/SharedLinksPanel.tsx b/frontend/src/components/admin/SharedLinksPanel.tsx
index 299073f..22017a3 100644
--- a/frontend/src/components/admin/SharedLinksPanel.tsx
+++ b/frontend/src/components/admin/SharedLinksPanel.tsx
@@ -2,7 +2,7 @@ import { Trash2, ExternalLink } from "lucide-react";
 import {
   useGetSharedLinksQuery,
   useDeleteSharedLinkMutation,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 
 function formatDate(unix: number): string {
   return new Date(unix * 1000).toLocaleString();
diff --git a/frontend/src/components/admin/SystemsPanel.test.tsx b/frontend/src/components/admin/SystemsPanel.test.tsx
index 0c158f3..4e51384 100644
--- a/frontend/src/components/admin/SystemsPanel.test.tsx
+++ b/frontend/src/components/admin/SystemsPanel.test.tsx
@@ -52,7 +52,7 @@ const noopMutate = vi.fn(() => ({
   unwrap: vi.fn().mockResolvedValue(undefined),
 }));
 
-vi.mock("@/hooks/useAdminWsOps", () => ({
+vi.mock("@/hooks/admin/useAdminWsOps", () => ({
   useListSystemsQuery: () => ({ data: mockSystems, isLoading: false }),
   useCreateSystemMutation: () => [createSystemMutate, {}],
   useUpdateSystemMutation: () => [updateSystemMutate, {}],
diff --git a/frontend/src/components/admin/SystemsPanel.tsx b/frontend/src/components/admin/SystemsPanel.tsx
index b7ddbc0..40b5562 100644
--- a/frontend/src/components/admin/SystemsPanel.tsx
+++ b/frontend/src/components/admin/SystemsPanel.tsx
@@ -18,7 +18,7 @@ import {
   useListTagsQuery,
   useGetConfigQuery,
   useUpdateConfigMutation,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { AdminSystem, AdminTalkgroup, AdminUnit } from "@/types";
 
 // ─── System card ───
diff --git a/frontend/src/components/admin/ToolsPanel.tsx b/frontend/src/components/admin/ToolsPanel.tsx
index 9073840..4d744a1 100644
--- a/frontend/src/components/admin/ToolsPanel.tsx
+++ b/frontend/src/components/admin/ToolsPanel.tsx
@@ -20,7 +20,7 @@ import {
   useLazyExportTagsQuery,
   useImportConfigMutation,
   useListSystemsQuery,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import { selectToken } from "@/app/slices/authSlice";
 import { useAppSelector } from "@/app/store";
 import RadioReferenceCard from "@/components/admin/RadioReferenceCard";
diff --git a/frontend/src/components/admin/TranscriptionPanel.tsx b/frontend/src/components/admin/TranscriptionPanel.tsx
index 4c2ad4d..812b01d 100644
--- a/frontend/src/components/admin/TranscriptionPanel.tsx
+++ b/frontend/src/components/admin/TranscriptionPanel.tsx
@@ -7,7 +7,7 @@ import {
   useTranscriptionDeleteMutation,
   useTranscriptionStatsQuery,
   useUpdateConfigMutation,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { WhisperModel } from "@/types";
 
 const KNOWN_MODELS = [
diff --git a/frontend/src/components/admin/UsersPanel.test.tsx b/frontend/src/components/admin/UsersPanel.test.tsx
index 07a08ab..a40ca7c 100644
--- a/frontend/src/components/admin/UsersPanel.test.tsx
+++ b/frontend/src/components/admin/UsersPanel.test.tsx
@@ -64,7 +64,7 @@ const deleteUserMutate = vi.fn((_arg: unknown) => ({
   unwrap: deleteUserUnwrap,
 }));
 
-vi.mock("@/hooks/useAdminWsOps", () => ({
+vi.mock("@/hooks/admin/useAdminWsOps", () => ({
   useListUsersQuery: () => ({ data: mockUsers, isLoading: false }),
   useListSystemsQuery: () => ({ data: mockSystems, isLoading: false }),
   useCreateUserMutation: () => [createUserMutate, {}],
diff --git a/frontend/src/components/admin/UsersPanel.tsx b/frontend/src/components/admin/UsersPanel.tsx
index 6babb8e..05325db 100644
--- a/frontend/src/components/admin/UsersPanel.tsx
+++ b/frontend/src/components/admin/UsersPanel.tsx
@@ -6,7 +6,7 @@ import {
   useCreateUserMutation,
   useUpdateUserMutation,
   useDeleteUserMutation,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { AdminUser, CreateUserPayload, UpdateUserPayload } from "@/types";
 
 interface UserFormState {
diff --git a/frontend/src/components/admin/WebhooksPanel.tsx b/frontend/src/components/admin/WebhooksPanel.tsx
index 168eaf2..e1efb56 100644
--- a/frontend/src/components/admin/WebhooksPanel.tsx
+++ b/frontend/src/components/admin/WebhooksPanel.tsx
@@ -5,7 +5,7 @@ import {
   useCreateWebhookMutation,
   useUpdateWebhookMutation,
   useDeleteWebhookMutation,
-} from "@/hooks/useAdminWsOps";
+} from "@/hooks/admin/useAdminWsOps";
 import type { AdminWebhook } from "@/types";
 
 interface WebhookFormState {
diff --git a/frontend/src/components/scanner/DisplayPanel.tsx b/frontend/src/components/scanner/DisplayPanel.tsx
index 9352a8d..26ec420 100644
--- a/frontend/src/components/scanner/DisplayPanel.tsx
+++ b/frontend/src/components/scanner/DisplayPanel.tsx
@@ -12,7 +12,7 @@ import { useGetBookmarkIDsQuery, useToggleBookmarkMutation } from "@/app/api";
 import { useShareCallMutation } from "@/app/slices/shareSlice";
 import { HistoryPanel } from "@/components/scanner/HistoryPanel";
 import { TranscriptPanel } from "@/components/scanner/TranscriptPanel";
-import { useActiveUnit } from "@/hooks/useActiveUnit";
+import { useActiveUnit } from "@/hooks/scanner/useActiveUnit";
 import { useAppSelector } from "@/app/store";
 import type { AvoidEntry, Call } from "@/types";
 
diff --git a/frontend/src/components/scanner/LEDPanel.test.tsx b/frontend/src/components/scanner/LEDPanel.test.tsx
index e6fec5b..b80b9b5 100644
--- a/frontend/src/components/scanner/LEDPanel.test.tsx
+++ b/frontend/src/components/scanner/LEDPanel.test.tsx
@@ -15,7 +15,7 @@ import type { Call, ScannerConfig } from "@/types";
 const mockToggle = vi.fn();
 let mockIsDark = true;
 
-vi.mock("@/hooks/useTheme", () => ({
+vi.mock("@/hooks/shared/useTheme", () => ({
   useTheme: () => ({
     isDark: mockIsDark,
     toggle: mockToggle,
diff --git a/frontend/src/components/scanner/LEDPanel.tsx b/frontend/src/components/scanner/LEDPanel.tsx
index 6bc8cf1..2e3fcf1 100644
--- a/frontend/src/components/scanner/LEDPanel.tsx
+++ b/frontend/src/components/scanner/LEDPanel.tsx
@@ -9,7 +9,7 @@ import {
 } from "lucide-react";
 import { useState, useRef, useEffect } from "react";
 import { useNavigate } from "react-router-dom";
-import { useTheme } from "@/hooks/useTheme";
+import { useTheme } from "@/hooks/shared/useTheme";
 import { useAppSelector, useAppDispatch } from "@/app/store";
 import {
   selectToken,
diff --git a/frontend/src/hooks/admin/index.ts b/frontend/src/hooks/admin/index.ts
new file mode 100644
index 0000000..70d3b46
--- /dev/null
+++ b/frontend/src/hooks/admin/index.ts
@@ -0,0 +1,5 @@
+export * from "./useAdminActivity";
+export * from "./useAdminLogs";
+export * from "./useAdminWebSocket";
+export * from "./useAdminWsOps";
+export * from "./useWsQuery";
diff --git a/frontend/src/hooks/useAdminActivity.ts b/frontend/src/hooks/admin/useAdminActivity.ts
similarity index 100%
rename from frontend/src/hooks/useAdminActivity.ts
rename to frontend/src/hooks/admin/useAdminActivity.ts
diff --git a/frontend/src/hooks/useAdminLogs.ts b/frontend/src/hooks/admin/useAdminLogs.ts
similarity index 100%
rename from frontend/src/hooks/useAdminLogs.ts
rename to frontend/src/hooks/admin/useAdminLogs.ts
diff --git a/frontend/src/hooks/useAdminWebSocket.ts b/frontend/src/hooks/admin/useAdminWebSocket.ts
similarity index 100%
rename from frontend/src/hooks/useAdminWebSocket.ts
rename to frontend/src/hooks/admin/useAdminWebSocket.ts
diff --git a/frontend/src/hooks/useAdminWsOps.ts b/frontend/src/hooks/admin/useAdminWsOps.ts
similarity index 99%
rename from frontend/src/hooks/useAdminWsOps.ts
rename to frontend/src/hooks/admin/useAdminWsOps.ts
index 838f22a..412a928 100644
--- a/frontend/src/hooks/useAdminWsOps.ts
+++ b/frontend/src/hooks/admin/useAdminWsOps.ts
@@ -1,4 +1,4 @@
-import { useWsQuery, useWsMutation, useLazyWsQuery } from "@/hooks/useWsQuery";
+import { useWsQuery, useWsMutation, useLazyWsQuery } from "@/hooks/admin/useWsQuery";
 import type {
   AdminUser,
   AdminSystem,
diff --git a/frontend/src/hooks/useWsQuery.ts b/frontend/src/hooks/admin/useWsQuery.ts
similarity index 100%
rename from frontend/src/hooks/useWsQuery.ts
rename to frontend/src/hooks/admin/useWsQuery.ts
diff --git a/frontend/src/hooks/index.ts b/frontend/src/hooks/index.ts
new file mode 100644
index 0000000..685bad6
--- /dev/null
+++ b/frontend/src/hooks/index.ts
@@ -0,0 +1,7 @@
+// Barrel re-export for the hooks tree. Prefer specific imports
+// (`@/hooks/shared/useTheme`) in new code; this barrel exists as a
+// safety net for callers that want to grab a hook without thinking
+// about which subfolder it lives in.
+export * from "./admin";
+export * from "./scanner";
+export * from "./shared";
diff --git a/frontend/src/hooks/scanner/index.ts b/frontend/src/hooks/scanner/index.ts
new file mode 100644
index 0000000..4ddb62a
--- /dev/null
+++ b/frontend/src/hooks/scanner/index.ts
@@ -0,0 +1,4 @@
+export * from "./useActiveUnit";
+export * from "./useAudioPlayer";
+export * from "./useScanner";
+export * from "./useTGSelectionSync";
diff --git a/frontend/src/hooks/useActiveUnit.ts b/frontend/src/hooks/scanner/useActiveUnit.ts
similarity index 100%
rename from frontend/src/hooks/useActiveUnit.ts
rename to frontend/src/hooks/scanner/useActiveUnit.ts
diff --git a/frontend/src/hooks/useAudioPlayer.ts b/frontend/src/hooks/scanner/useAudioPlayer.ts
similarity index 100%
rename from frontend/src/hooks/useAudioPlayer.ts
rename to frontend/src/hooks/scanner/useAudioPlayer.ts
diff --git a/frontend/src/hooks/useScanner.ts b/frontend/src/hooks/scanner/useScanner.ts
similarity index 95%
rename from frontend/src/hooks/useScanner.ts
rename to frontend/src/hooks/scanner/useScanner.ts
index 46a3aca..b2e4837 100644
--- a/frontend/src/hooks/useScanner.ts
+++ b/frontend/src/hooks/scanner/useScanner.ts
@@ -1,7 +1,7 @@
 import { useCallback } from "react";
 import { useAppDispatch, useAppSelector } from "@/app/store";
-import { useWebSocket } from "@/hooks/useWebSocket";
-import { useAudioPlayer } from "@/hooks/useAudioPlayer";
+import { useWebSocket } from "@/hooks/shared/useWebSocket";
+import { useAudioPlayer } from "@/hooks/scanner/useAudioPlayer";
 import {
   togglePause,
   toggleLive,
diff --git a/frontend/src/hooks/useTGSelectionSync.ts b/frontend/src/hooks/scanner/useTGSelectionSync.ts
similarity index 100%
rename from frontend/src/hooks/useTGSelectionSync.ts
rename to frontend/src/hooks/scanner/useTGSelectionSync.ts
diff --git a/frontend/src/hooks/shared/index.ts b/frontend/src/hooks/shared/index.ts
new file mode 100644
index 0000000..23dba99
--- /dev/null
+++ b/frontend/src/hooks/shared/index.ts
@@ -0,0 +1,4 @@
+export * from "./useAuthInit";
+export * from "./useTheme";
+export * from "./useTokenRefresh";
+export * from "./useWebSocket";
diff --git a/frontend/src/hooks/useAuthInit.test.tsx b/frontend/src/hooks/shared/useAuthInit.test.tsx
similarity index 98%
rename from frontend/src/hooks/useAuthInit.test.tsx
rename to frontend/src/hooks/shared/useAuthInit.test.tsx
index 21ec627..2a8dec4 100644
--- a/frontend/src/hooks/useAuthInit.test.tsx
+++ b/frontend/src/hooks/shared/useAuthInit.test.tsx
@@ -8,7 +8,7 @@ import { authSlice } from "@/app/slices/authSlice";
 import { callsSlice } from "@/app/slices/callsSlice";
 import { api } from "@/app/api";
 import type { RootState } from "@/app/store";
-import { useAuthInit } from "@/hooks/useAuthInit";
+import { useAuthInit } from "@/hooks/shared/useAuthInit";
 
 // ── Mock the refresh mutation ─────────────────────────────────────────────
 
diff --git a/frontend/src/hooks/useAuthInit.ts b/frontend/src/hooks/shared/useAuthInit.ts
similarity index 100%
rename from frontend/src/hooks/useAuthInit.ts
rename to frontend/src/hooks/shared/useAuthInit.ts
diff --git a/frontend/src/hooks/useTheme.ts b/frontend/src/hooks/shared/useTheme.ts
similarity index 100%
rename from frontend/src/hooks/useTheme.ts
rename to frontend/src/hooks/shared/useTheme.ts
diff --git a/frontend/src/hooks/useTokenRefresh.test.tsx b/frontend/src/hooks/shared/useTokenRefresh.test.tsx
similarity index 98%
rename from frontend/src/hooks/useTokenRefresh.test.tsx
rename to frontend/src/hooks/shared/useTokenRefresh.test.tsx
index a847688..484e8e5 100644
--- a/frontend/src/hooks/useTokenRefresh.test.tsx
+++ b/frontend/src/hooks/shared/useTokenRefresh.test.tsx
@@ -6,7 +6,7 @@ import { scannerSlice } from "@/app/slices/scannerSlice";
 import { authSlice, setCredentials } from "@/app/slices/authSlice";
 import { callsSlice } from "@/app/slices/callsSlice";
 import { api } from "@/app/api";
-import { useTokenRefresh } from "@/hooks/useTokenRefresh";
+import { useTokenRefresh } from "@/hooks/shared/useTokenRefresh";
 
 // ── Mocks ────────────────────────────────────────────────────────────────
 
diff --git a/frontend/src/hooks/useTokenRefresh.ts b/frontend/src/hooks/shared/useTokenRefresh.ts
similarity index 100%
rename from frontend/src/hooks/useTokenRefresh.ts
rename to frontend/src/hooks/shared/useTokenRefresh.ts
diff --git a/frontend/src/hooks/useWebSocket.ts b/frontend/src/hooks/shared/useWebSocket.ts
similarity index 100%
rename from frontend/src/hooks/useWebSocket.ts
rename to frontend/src/hooks/shared/useWebSocket.ts
diff --git a/frontend/src/main.tsx b/frontend/src/main.tsx
index a388999..84365bd 100644
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@@ -5,8 +5,8 @@ import { BrowserRouter, Routes, Route } from "react-router-dom";
 import { store } from "@/app/store";
 import { useAppSelector } from "@/app/store";
 import { selectAuthReady } from "@/app/slices/authSlice";
-import { useAuthInit } from "@/hooks/useAuthInit";
-import { useTokenRefresh } from "@/hooks/useTokenRefresh";
+import { useAuthInit } from "@/hooks/shared/useAuthInit";
+import { useTokenRefresh } from "@/hooks/shared/useTokenRefresh";
 import "@/index.css";
 
 const Scanner = lazy(() => import("@/pages/Scanner"));
diff --git a/frontend/src/pages/Scanner.tsx b/frontend/src/pages/Scanner.tsx
index d470b69..2de844b 100644
--- a/frontend/src/pages/Scanner.tsx
+++ b/frontend/src/pages/Scanner.tsx
@@ -9,8 +9,8 @@ import {
   setLive,
   resetDisplay,
 } from "@/app/slices/scannerSlice";
-import { useScanner } from "@/hooks/useScanner";
-import { useTGSelectionSync } from "@/hooks/useTGSelectionSync";
+import { useScanner } from "@/hooks/scanner/useScanner";
+import { useTGSelectionSync } from "@/hooks/scanner/useTGSelectionSync";
 import { LEDPanel } from "@/components/scanner/LEDPanel";
 import { DisplayPanel } from "@/components/scanner/DisplayPanel";
 import { ControlToolbar } from "@/components/scanner/ControlToolbar";