tfm_ainventory/docs/superpowers/specs/2026-04-18-ai-friendly-refactor-design.md

AI-Friendly Code Refactoring Design

Date: 2026-04-18
Status: Design Review
Approach: Test-First, Full Coverage, Functional Preservation

---

1. Executive Summary

Refactor the codebase to be "AI-friendly" by breaking monolithic files into smaller, focused modules (<300 lines) while maintaining 100% functional parity. Strategy: Test Everything First → Refactor by Priority → Validate Continuously.

Risk Mitigation: Previous session left GUI broken (50% functional). This design ensures zero regression through comprehensive test coverage before any code changes.

---

2. Current State & Problem

Metric	Current	Target
Test Files	1 (backend only)	30+ (backend + frontend)
Frontend Test Coverage	0%	80%+
Largest File	979 lines (page.tsx)	<300 lines
Cyclomatic Complexity	Unknown (likely >10)	<10 per function
Files >300 lines	8 critical	0

Critical Files to Refactor (Priority Order):

1. Backend (Phase 1):

   • backend/routers/users.py (443 lines)
   • backend/routers/operations.py (298 lines)
   • backend/routers/items.py (240 lines)

2. Components (Phase 2):

   • frontend/components/AIOnboarding.tsx (641 lines)
   • frontend/components/Scanner.tsx (367 lines)
   • frontend/components/AdminOverlay.tsx (253 lines)

3. Pages (Phase 3):

   • frontend/app/page.tsx (979 lines)
   • frontend/app/inventory/page.tsx (857 lines)
   • frontend/app/logs/page.tsx (341 lines)

---

3. Testing Strategy: Comprehensive Coverage

3.1 Backend Testing (Pytest)

Target: 85%+ coverage of all routers, models, auth, business logic.

Structure:

backend/tests/
├── test_admin.py          (existing - expand)
├── test_users.py          (new - auth, CRUD)
├── test_items.py          (new - inventory ops)
├── test_operations.py     (new - check-in/out)
├── test_categories.py     (new - category mgmt)
├── test_ai_extraction.py  (new - AI pipeline)
├── test_offline_sync.py   (new - UUID idempotency)
└── conftest.py            (shared fixtures)

Test Types:

• Unit tests: Individual functions (validators, formatters)
• Integration tests: Full API workflows (auth → CRUD → audit log)
• Fixtures: Mocked auth, test DB (in-memory SQLite), AI responses

Coverage Targets:

• routers/: 85%
• models.py: 90% (data integrity critical)
• auth.py: 90% (security critical)
• ai/: 80% (extraction pipeline)

3.2 Frontend Testing (Vitest)

Target: 80%+ coverage of components, hooks, utilities.

Structure:

frontend/tests/
├── components/
│   ├── Scanner.test.tsx
│   ├── AIOnboarding.test.tsx
│   ├── AdminOverlay.test.tsx
│   ├── IdentityCheckOverlay.test.tsx
│   └── ...
├── hooks/
│   ├── useAdmin.test.ts
│   └── useSync.test.ts (if exists)
├── lib/
│   ├── api.test.ts
│   └── labels.test.ts
└── integration/
    ├── scanner-workflow.test.tsx
    └── inventory-workflow.test.tsx

Test Types:

• Unit: Component rendering, prop validation, event handlers
• Hook tests: State updates, side effects, async operations
• Integration: Multi-component workflows (scanner → validation → sync)
• Snapshot tests: Critical UI layouts (StatCard, BottomNav)

Coverage Targets:

• Components: 80%
• Hooks: 85%
• Utils/lib: 90%
• Pages: Covered by integration tests (lower % due to complexity)

3.3 E2E Testing (Playwright)

Target: Critical user paths only (avoid bloat).

Workflows to Automate:

1. Login flow
2. Scan item → Match → Stock adjustment
3. Create new item (AI extraction)
4. Admin settings change
5. Offline sync (simulate network loss)

Coverage: 5-8 test suites, ~30 min total runtime.

---

4. Refactoring Approach: Functional Preservation

4.1 Refactoring Rules

All refactors must satisfy:

1. File Size Limit: Files ≤300 lines (AGENTS.md standard)
2. Complexity Limit: Cyclomatic complexity <10 per function (AGENTS.md)
3. Export Clarity: Each module has ONE clear purpose
4. No Behavior Change: Tests pass 100% before and after
5. Internal-only refactors: No public API changes unless documented

4.2 Refactoring Strategy by Phase

Phase 1: Backend Routers

• Extract route handlers into smaller service modules
• Split users.py (443 lines) into:
  • services/user_service.py (CRUD logic)
  • validators/user_validator.py (input validation)
  • routers/users.py (endpoints only, <150 lines)
• Repeat for operations.py, items.py

Phase 2: Components

• Split large components into smaller sub-components
• Extract state management logic into custom hooks
• Example: AIOnboarding.tsx (641 lines) →
  • components/AIOnboarding.tsx (orchestrator, <150 lines)
  • components/AIOnboarding/StepValidator.tsx
  • components/AIOnboarding/ImageCapture.tsx
  • hooks/useAIExtraction.ts (AI logic)

Phase 3: Pages

• Extract page logic into custom hooks
• Move form components into separate files
• Example: app/page.tsx (979 lines) →
  • app/page.tsx (layout only, <100 lines)
  • components/InventoryDashboard.tsx (dashboard logic)
  • hooks/useDashboardData.ts

---

5. Testing & Refactoring Workflow

5.1 Phase 1: Backend Tests (Week 1)

Steps:

1. Create backend/tests/ suite with 7 test files
2. Write integration tests for all routers (baseline)
3. Add unit tests for critical functions
4. Achieve 85%+ coverage
5. All tests PASS before any code changes

Validation:

pytest backend/tests/ --cov=backend --cov-report=html
# Expected: 85%+ coverage, all tests passing

5.2 Phase 2: Frontend Tests (Week 2)

Steps:

1. Create frontend/tests/ suite with component + hook tests
2. Test all components (Scanner, AIOnboarding, AdminOverlay, etc.)
3. Test all custom hooks (useAdmin, etc.)
4. Add snapshot tests for UI layouts
5. Achieve 80%+ coverage

Validation:

npm test -- --coverage
# Expected: 80%+ coverage, all tests passing

5.3 Phase 3: E2E Tests (Week 2)

Steps:

1. Create 5-8 Playwright test suites for critical workflows
2. Login → Scan → Stock adjustment
3. Create new item with AI
4. Admin config changes
5. Offline sync

Validation:

npx playwright test
# Expected: All workflows automated, <30min runtime

5.4 Phase 4: Backend Refactoring + Testing

For each module (users.py, operations.py, items.py):

1. Run full backend test suite (PASS)
2. Refactor: Split into smaller modules
3. Run full backend test suite again (PASS)
4. Verify no behavior changes
5. Commit with message: refactor: split {module} into smaller modules

Gating: No refactor commit until all tests pass.

5.5 Phase 5: Component Refactoring + Testing

For each component (AIOnboarding, Scanner, etc.):

1. Run Vitest suite for component (PASS)
2. Refactor: Split into sub-components + hooks
3. Run Vitest suite again (PASS)
4. Manual browser test: Verify UI unchanged
5. Commit: refactor: decompose {component} into smaller modules

5.6 Phase 6: Page Refactoring + Testing

For each page (page.tsx, inventory/page.tsx, etc.):

1. Run Vitest + e2e tests for page (PASS)
2. Refactor: Extract logic into hooks + components
3. Run tests again (PASS)
4. Manual browser test: All buttons/features work
5. Commit: refactor: extract {page} logic into hooks

---

6. Functional Preservation: Validation Checkpoints

Pre-Refactoring Baseline (Week 1-2)

Test Suite Created & Passing:

• ✅ 85%+ backend coverage (pytest)
• ✅ 80%+ frontend coverage (vitest)
• ✅ 5+ e2e workflows automated (playwright)
• ✅ Manual checklist signed off (UI inspection)

Manual Validation Checklist (Browser):

[ ] Login works (LDAP + local)
[ ] Scan item → matches inventory
[ ] Scan new item → AI extraction popup
[ ] Create category → appears in dropdown
[ ] Admin page loads → all sections visible
[ ] Scanner viewport responsive (mobile + desktop)
[ ] Offline mode: scan offline → sync on reconnect
[ ] Buttons/icons visible + clickable
[ ] No console errors

Post-Refactoring Validation (After each phase)

Automated Tests Must Pass:

pytest backend/tests/ --cov=backend
npm test -- --coverage
npx playwright test

Manual Tests (Regression Checklist):

• Same checklist as above
• Focus on the refactored module
• Test mobile (320px, 768px viewports)
• Test accessibility (keyboard nav, focus indicators)

Diff Inspection:

• Code review each commit
• Verify no logic changes (only structure)
• Ensure no hidden side effects

---

7. AGENTS.md Updates

New sections to add:

Testing Standards

## Testing Strategy (AI-Friendly Refactoring)
- **Backend:** Pytest with 85%+ coverage (unit + integration tests)
- **Frontend:** Vitest with 80%+ coverage (components, hooks, snapshots)
- **E2E:** Playwright for critical workflows (login, scan, sync)
- **Coverage Tools:** --cov=backend for pytest, --coverage for vitest
- **Test-First Approach:** All tests written and passing BEFORE refactoring
- **Functional Preservation:** Zero behavior changes; all tests must pass pre/post refactor

Refactoring Guidelines

## Code Refactoring (AI-Friendly Modularity)
- **Target:** Break monolithic files into focused modules (<300 lines)
- **Phases:** Backend → Components → Pages
- **Validation:** Tests PASS before and after each refactor
- **Gating:** No refactor commit without passing test suite
- **Regression:** Manual checklist + automated tests catch UI breakage

Git Conventions (Add to existing)

- Refactoring commits: `refactor: split {module} into smaller modules`
- Testing commits: `test: add {suite} coverage for {module}`
- All commits must include test results in message body

---

8. Risk Mitigation

Problem: Previous session = GUI broken 50% post-refactor.

Solution in this Design:

• ✅ Comprehensive test coverage BEFORE refactoring (prevents breakage)
• ✅ Tests as gating condition (no code changes if tests fail)
• ✅ Manual checklist for UI regression (buttons, cards, functions)
• ✅ E2E workflows for critical paths (scan, sync, admin)
• ✅ Phased approach (validate each phase before moving to next)
• ✅ Rollback capability (git history preserved; revert if needed)

---

9. Timeline & Effort

Phase	Duration	Deliverable
Phase 1: Backend Tests	3 days	7 test files, 85%+ coverage
Phase 2: Frontend Tests	3 days	Component + hook tests, 80%+ coverage
Phase 3: E2E Tests	2 days	5+ Playwright workflows
Phase 4: Backend Refactor	5 days	3 routers split, tests passing
Phase 5: Component Refactor	5 days	3-4 components split, tests passing
Phase 6: Page Refactor	4 days	3 pages refactored, tests passing
Total	~22 days	AI-friendly codebase, 100% functional

---

10. Success Criteria

✅ All Tests Passing

• Backend: 85%+ coverage (pytest)
• Frontend: 80%+ coverage (vitest)
• E2E: All 5+ workflows automated

✅ Files Refactored

• Zero files >300 lines (except config/generated files)
• All functions <10 complexity

✅ Functional Parity

• All buttons/cards/functions visible and working
• No UI regression (vs. current v1.10.16)
• Offline sync still works
• AI extraction still works

✅ Documentation

• AGENTS.md updated with testing + refactoring guidelines
• Comments added to extracted modules explaining purpose

✅ Git History

• Clean commit chain: test → refactor (alternating)
• No force pushes; full history preserved

---

Next Steps (If Approved)

1. Create new branch refactor/ai-friendly from dev
2. Begin Phase 1: Backend test suite
3. Validate baseline (all tests passing)
4. Proceed to Phase 2-6 in sequence
5. Update AGENTS.md during Phase 1
6. Final validation before merging back to dev