punimtag/FOLDER_PICKER_ANALYSIS.md

Folder Picker Analysis - Getting Full Paths

Problem

Browsers don't expose full file system paths for security reasons. Current implementation only gets folder names, not full absolute paths.

Current Limitations

Browser-Based Solutions (Current)

1. File System Access API (showDirectoryPicker)

   • ✅ No confirmation dialog
   • ❌ Only returns folder name, not full path
   • ❌ Only works in Chrome 86+, Edge 86+, Opera 72+

2. webkitdirectory input

   • ✅ Works in all browsers
   • ❌ Shows security confirmation dialog
   • ❌ Only returns relative paths, not absolute paths

Alternative Solutions

✅ Option 1: Backend API with Tkinter (RECOMMENDED)

How it works:

• Frontend calls backend API endpoint
• Backend uses tkinter.filedialog.askdirectory() to show native folder picker
• Backend returns full absolute path to frontend
• Frontend populates the path input

Pros:

• ✅ Returns full absolute path
• ✅ Native OS dialog (looks native on Windows/Linux/macOS)
• ✅ No browser security restrictions
• ✅ tkinter already used in project
• ✅ Cross-platform support
• ✅ No confirmation dialogs

Cons:

• ⚠️ Requires backend to be running on same machine as user
• ⚠️ Backend needs GUI access (tkinter requires display)
• ⚠️ May need X11 forwarding for remote servers

Implementation:

# Backend API endpoint
@router.post("/browse-folder")
def browse_folder() -> dict:
    """Open native folder picker and return selected path."""
    import tkinter as tk
    from tkinter import filedialog
    
    # Create root window (hidden)
    root = tk.Tk()
    root.withdraw()  # Hide main window
    root.attributes('-topmost', True)  # Bring to front
    
    # Show folder picker
    folder_path = filedialog.askdirectory(
        title="Select folder to scan",
        mustexist=True
    )
    
    root.destroy()
    
    if folder_path:
        return {"path": folder_path, "success": True}
    else:
        return {"path": "", "success": False, "message": "No folder selected"}

// Frontend API call
const browseFolder = async (): Promise<string | null> => {
  const { data } = await apiClient.post<{path: string, success: boolean}>(
    '/api/v1/photos/browse-folder'
  )
  return data.success ? data.path : null
}

---

Option 2: Backend API with PyQt/PySide

How it works:

• Similar to Option 1, but uses PyQt/PySide instead of tkinter
• More modern UI, but requires additional dependency

Pros:

• ✅ Returns full absolute path
• ✅ More modern-looking dialogs
• ✅ Better customization options

Cons:

• ❌ Requires additional dependency (PyQt5/PyQt6/PySide2/PySide6)
• ❌ Larger package size
• ❌ Same GUI access requirements as tkinter

---

Option 3: Backend API with Platform-Specific Tools

How it works:

• Use platform-specific command-line tools to open folder pickers
• Windows: PowerShell script
• Linux: zenity, kdialog, or yad
• macOS: AppleScript

Pros:

• ✅ Returns full absolute path
• ✅ No GUI framework required
• ✅ Works on headless servers with X11 forwarding

Cons:

• ❌ Platform-specific code required
• ❌ Requires external tools to be installed
• ❌ More complex implementation
• ❌ Less consistent UI across platforms

Example (Linux with zenity):

import subprocess
import platform

def browse_folder_zenity():
    result = subprocess.run(
        ['zenity', '--file-selection', '--directory'],
        capture_output=True,
        text=True
    )
    return result.stdout.strip() if result.returncode == 0 else None

---

Option 4: Electron App (Not Applicable)

How it works:

• Convert web app to Electron app
• Use Electron's dialog.showOpenDialog() API

Pros:

• ✅ Returns full absolute path
• ✅ Native OS dialogs
• ✅ No browser restrictions

Cons:

• ❌ Requires complete app restructuring
• ❌ Not applicable (this is a web app, not Electron)
• ❌ Much larger application size

---

Option 5: Custom File Browser UI

How it works:

• Build custom file browser in React
• Backend API provides directory listings
• User navigates through folders in UI
• Select folder when found

Pros:

• ✅ Full control over UI/UX
• ✅ Can show full paths
• ✅ No native dialogs needed

Cons:

• ❌ Complex implementation
• ❌ Requires multiple API calls
• ❌ Slower user experience
• ❌ Need to handle permissions, hidden files, etc.

---

Recommendation

✅ Use Option 1: Backend API with Tkinter

This is the best solution because:

1. tkinter is already used in the project (face_processing.py)
2. Simple implementation - just one API endpoint
3. Returns full paths - solves the core problem
4. Native dialogs - familiar to users
5. No additional dependencies - tkinter is built into Python
6. Cross-platform - works on Windows, Linux, macOS

Implementation Steps

1. Create backend API endpoint (/api/v1/photos/browse-folder)

   • Use tkinter.filedialog.askdirectory()
   • Return selected path as JSON

2. Add frontend API method

   • Call the new endpoint
   • Handle response and populate path input

3. Update Browse button handler

   • Call backend API instead of browser picker
   • Show loading state while waiting
   • Handle errors gracefully

4. Fallback option

   • Keep browser-based picker as fallback
   • Use if backend API fails or unavailable

Considerations

• Headless servers: If backend runs on headless server, need X11 forwarding or use Option 3 (platform-specific tools)
• Remote access: If users access from remote machines, backend must be on same machine as user
• Error handling: Handle cases where tkinter dialog can't be shown (no display, permissions, etc.)

---

Quick Comparison Table

Solution	Full Path	Native Dialog	Dependencies	Complexity	Recommended
Backend + Tkinter	✅	✅	None (built-in)	Low	✅ YES
Backend + PyQt	✅	✅	PyQt/PySide	Medium	⚠️ Maybe
Platform Tools	✅	✅	zenity/kdialog/etc	High	⚠️ Maybe
Custom UI	✅	❌	None	Very High	❌ No
Electron	✅	✅	Electron	Very High	❌ No
Browser API	❌	✅	None	Low	❌ No

---

Next Steps

1. Implement backend API endpoint with tkinter
2. Add frontend API method
3. Update Browse button to use backend API
4. Add error handling and fallback
5. Test on all platforms (Windows, Linux, macOS)