tfm_ainventory/artifacts/superpowers/brainstorm.md

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).