## Goal
Reduce the technical debt and cognitive load inherited from large source files (some exceeding 1000 lines) by refactoring them into modular, functional units. The target is to align with the project rule of keeping files significantly under 300 lines where possible, improving maintainability and developer velocity.

## Constraints
- **Maintain Parity**: No functional changes or regressions allowed during refactoring.
- **Stack Consistency**: Maintain Next.js 15 (React 19) and FastAPI patterns.
- **Prop Drilling**: Avoid excessive prop drilling; use Context or efficient state sharing where logical.
- **Type Safety**: Maintain strict TypeScript definitions throughout the refactoring process.

## Known context
- **Frontend Hotspots**: `admin/page.tsx` (1039 lines), `inventory/page.tsx` (858 lines), and the main `page.tsx` (910 lines) are the primary pain points.
- **Backend Hotspots**: `routers/users.py` and `routers/admin_db.py` consolidate too many distinct administrative tasks.
- **Existing Components**: There is already a `components/` directory, indicating an established pattern for extraction.

## Risks
- **Context Fragmentation**: Splitting state-heavy components can make tracking data flow harder if not documented.
- **Build Errors**: Next.js App Router is sensitive to client/server component boundaries during refactoring.
- **Refactoring Fatigue**: Large-scale changes across multiple critical files can introduce subtle bugs in event handlers or API sync logic.

## Options (2–4)

### Option 1: Functional Component Extraction (UI-First)
Extract major UI sections (e.g., Modals, Tab Panels, Complex List Items) into the `components/` directory. For `admin/page.tsx`, this would mean creating `LDAPSettings.tsx`, `DatabaseSettings.tsx`, and `AISettings.tsx`.
*   **Pros**: Immediate reduction in file size; easier to style in isolation.
*   **Cons**: Might require passing many props/callbacks.

### Option 2: Custom Hook Logic Extraction (Logic-First)
Move all `useState`, `useEffect`, and API call logic from the pages into custom hooks (e.g., `useAdminSettings.ts`, `useInventoryData.ts`).
*   **Pros**: Separates "How it works" from "How it looks"; reusable logic.
*   **Cons**: Requires careful handling of dependency arrays and closure-related state bugs.

### Option 3: Modular Sub-Routing (Backend)
Split the backend `users.py` and `admin_db.py` into smaller files based on specific functional domains (e.g., `admin_core.py`, `admin_backups.py`, `user_auth.py`).
*   **Pros**: Cleaner API paths and documentation; easier unit testing.
*   **Cons**: Requires updating `main.py` router inclusions.

## Recommendation
**Hybrid Approach (Options 1 & 2)**: Focus on the "Big 3" frontend pages first.
1.  **Extract Modals and Sections**: Move heavy UI blocks from `admin` and `inventory` into standalone components.
2.  **Extract Data Logic**: Create custom hooks for the most complex state-management sections (like the multi-step `AIOnboarding` or the complex sync logic in `inventory`).
3.  **Split Backend Routers**: Break down `users.py` and `admin_db.py` into functional sub-modules.

## Acceptance criteria
- [ ] No single file in the `app/` or `routers/` directory exceeds 400 lines (aiming for 300).
- [ ] The dashboard, inventory manager, and scanner function exactly as in `v1.9.24`.
- [ ] TypeScript compilation passes without errors (`npm run build` equivalent).
- [ ] All new components use the established `StatCard` and CSS patterns (Tailwind).