tfm_ainventory/.planning/PHASE6-DEBUG-PLAN.md

Phase 6 Debug & Fix Plan - Systematic Root Cause Analysis

Status: Phase 1 COMPLETE - Root Causes Identified
Date: 2026-04-23
Severity: CRITICAL - Multiple features broken

---

ROOT CAUSES IDENTIFIED (Phase 1)

1. Missing Item Creation UI ✓ FOUND

Evidence: Inventory page has no "+" button or create item modal

• Plus icon imported but never used in current inventory page
• Previous version (0881b0ec) had Plus icon in "Buy More" button
• Current version: Plus icon present but no create/add functionality
• Root Cause: Item creation UI was removed/refactored but not replaced
• Commits Involved: Possibly 3be455de, 37b6d295, b1a63e98

2. Missing Search Modal (Ctrl+K) ✓ FOUND

Evidence: User reports no Ctrl+K functionality

• SearchModal component imported and state exists (line 86, 817)
• Modal opens on button click (line 286)
• Root Cause: Ctrl+K keyboard shortcut not implemented or wired
• Component: frontend/components/inventory/SearchModal.tsx
• Issue: Missing useEffect for Ctrl+K listener

3. "Failed to process image with AI" ✓ CONTEXT

Evidence: User sees this error when trying to add items

• Backend logs show no errors → problem is in frontend/API call
• Likely triggered by missing item creation form
• Root Cause: Cannot test because item creation UI is missing
• Follow-up: Fix item creation UI first, then test AI integration

4. "Failed to delete from database" ✓ CONTEXT

Evidence: User reports this error

• Item.id is properly optional (id?: number) ✓
• Delete function exists (line 194: deleteItem)
• Root Cause: Cannot test because no items can be created
• Follow-up: Create items first, then test delete

5. "Failed to load admin data" ✓ CONTEXT

Evidence: Admin panel fails to load

• Backend startup successful, CORS configured
• Root Cause: Likely API path issue from Caddy proxy configuration
• Follow-up: Check admin API endpoints after basic functionality works

---

Phase 2 Pattern Analysis: Known Working vs Broken

Component Comparison

Component	Status	Issue
SearchModal	Imported ✓	Ctrl+K listener missing
QuantityAdjustmentModal	Imported ✓	Can't test - no items
Scanner	Imported ✓	Unused in inventory view
Item Creation	Missing ✗	UI completely removed
Admin API	Unknown	Needs separate test

Frontend Architecture Issue

The inventory page has been refactored to focus on:

• Search (SearchModal)
• Quantity adjustment
• Box manager

But lost:

• Item creation (the "+ Add" button)
• Manual item entry form

Pattern: Modular components built but orchestration broken.

---

Phase 3 Hypotheses (Ordered by Likelihood)

H1: Item Creation Moved to Scanner-Only (MOST LIKELY)

• Hypothesis: Items can only be created via scanner/AI extraction now
• Evidence: Scanner component imported but inventory page doesn't show it prominently
• Test: Check if Scanner is the create path now
• Expected: Search for item creation in scanner flow

H2: Item Creation Modal Hidden/Not Rendering (LIKELY)

• Hypothesis: Create modal exists but conditional render failed
• Evidence: Plus icon imported, item state exists, but modal JSX missing
• Test: Search for modal render code in inventory page
• Expected: Find commented-out or conditionally hidden create modal

H3: Item Creation in Separate Route (POSSIBLE)

• Hypothesis: Item creation moved to /inventory/new or separate page
• Evidence: No create UI in main inventory page
• Test: Check routes and components
• Expected: Find create item page elsewhere

H4: Complete Feature Removal (UNLIKELY)

• Hypothesis: Item creation feature was intentionally removed
• Evidence: Phase 5-6 focused on quantity adjust, search, export
• Test: Check ROADMAP and commit messages
• Expected: Find discussion about removing manual entry

---

Phase 4: Automated Testing Plan

Test Suite Structure

tests/
├── phase6_regression_tests.py (backend)
├── phase6_regression_tests.spec.ts (frontend)
└── phase6_api_tests.sh (curl-based)

Priority Test Order

1. Create Item (foundation - blocks all other tests)
2. Fetch Items (read - verify DB)
3. Delete Item (delete - verify cascade)
4. Search Item (search - test modal)
5. Admin API (admin - test load)

Test Execution Plan

All tests will be:

• Automated (no manual UI interaction required)
• Comprehensive (cover success + failure paths)
• Logged (results written to file for review)
• Non-destructive (can run multiple times)

---

Immediate Actions

Next Steps (Do NOT Skip Phase 1-3!)

1. H1 Test (5 min): Check if Scanner is the create path

   • Search for item creation in Scanner component
   • Check if scanner output goes to items table

2. H2 Test (5 min): Search inventory page JSX for create modal

   • Grep for "create|add|new.*item" in full JSX render
   • Check if modal code is commented out

3. H3 Test (5 min): Check app routes

   • Look in frontend/app for /new, /create, /item routes
   • Check if separate create page exists

4. Then Implement H1-H3 Findings

   • Based on which hypothesis is true, fix
   • DO NOT skip to fix without confirming root cause

5. Write Automated Tests (Phase 4)

   • Create test suite for each broken feature
   • Run all tests to verify fixes

---

Success Criteria

✅ Phase 6 Testing Complete ONLY when:

• Item creation works (can add item)
• Item deletion works (can delete item)
• Search modal works (Ctrl+K opens, finds items)
• Quantity adjustment works (can change qty)
• Admin panel loads (can access admin data)
• All automated tests pass
• No console errors on any action
• Backend logs show no errors

---

Key Files to Investigate

Frontend:

• frontend/app/inventory/page.tsx - Main inventory page (NEEDS + button)
• frontend/components/Scanner.tsx - Check if this is create path now
• frontend/components/inventory/SearchModal.tsx - Ctrl+K listener
• frontend/app/layout.tsx - Check for global Ctrl+K listener

Backend:

• backend/main.py - Check admin endpoints
• backend/routes/ - Verify all endpoints exist

Deployment:

• start_servers.py - Verify all services actually running
• Caddyfile.standalone - Check if routing correct to backend

---

NOT YET INVESTIGATED

• API endpoint authentication (Bearer token)
• Caddy proxy SSL certificate issues
• Database schema changes
• AI service configuration
• Offline sync state

(These will be investigated after item creation is fixed)

---

CRITICAL FINDING: AUTHENTICATION IS THE ROOT CAUSE

Phase 1 Investigation Results:

• ✅ Backend API exists and is running (OpenAPI endpoint responding)
• ✅ Frontend loads successfully (HTML responding)
• ❌ ALL API endpoints return 401 Not Authenticated
• ❌ Login endpoint rejects all credentials ("Invalid username or password, or insufficient permissions")
• ❌ Frontend has NO WAY TO AUTHENTICATE after startup

Why user sees errors:

1. Frontend loads → calls /items/ → 401 → error message "Failed to process image with AI"
2. Frontend tries to delete → calls /items/{id} → 401 → "Failed to delete from database"
3. Frontend tries to load admin → calls /admin/db/stats → 401 → "Failed to load admin data"
4. Frontend tries to search → calls /items/search → 401 → fails silently

Root Cause: Deployment doesn't have login credentials configured or auth bypass enabled

What Needs to Happen

Option A: Provide Credentials (Production)

• Configure LDAP server (requires external service)
• OR set hardcoded admin user in database
• Frontend then logs in before accessing API

Option B: Disable Auth for Development (Dev/Testing)

• Modify backend to allow unauthenticated access
• Remove @auth_guard decorators
• OR create test credentials in database

Option C: Fix Frontend Login Flow (If login exists but broken)

• Check if login page is accessible at /login
• Verify login form is wired to /users/login endpoint
• Check if token is stored in localStorage/sessionStorage

---

Phase 1 COMPLETE: AUTHENTICATION FAILURE is the root cause
Phase 2: Determine which option above to implement
Phase 3: Test hypothesis with automated tests
Phase 4: Apply fix and verify