🔧 [Refactor] Geographic Search Fails Silently

[mahula]

🔧 Refactor

Problem

Geographic search using the external Photon Komoot API fails silently when the API is unavailable, providing no user feedback and leaving users confused about why location search isn't working.

Reproducible Scenarios

Scenario 1: External API Server Error

1. Start the application normally
2. Search for a location (e.g., "Berlin", "London")
3. Photon Komoot API returns 500 error
4. Result: No geographic results appear, no error message shown to user

Scenario 2: Network Connectivity Issues

1. Start the application
2. Disconnect internet connection
3. Search for a location
4. Result: Geographic search silently fails, user gets no feedback

Scenario 3: API Rate Limiting

1. Perform many rapid geographic searches
2. Photon API rate limits the requests
3. Result: Subsequent searches fail silently without user notification

Scenario 4: Invalid API Response

1. Photon API returns malformed JSON
2. Search for any location
3. Result: Geographic search breaks silently

Root Cause

In lib/src/Components/Map/Subcomponents/Controls/SearchControl.tsx (lines 67-76), the geographic search only logs errors to console without user feedback:

const searchGeo = async () => {
  try {
    const { data } = await axios.get(`https://photon.komoot.io/api/?q=${value}&limit=5`)
    setGeoResults(data.features)
  } catch (error) {
    console.log(error)  // ← Only logs, no user feedback
    // Missing: setGeoResults([]) to clear stale results
    // Missing: User notification about the failure
  }
}

Current Architecture Analysis

Geographic Search Integration:

• External Dependency: Uses Photon Komoot API (https://photon.komoot.io/api/)
• Parallel Search: Runs alongside item search, tag search, and coordinate validation
• Debounced Execution: 500ms debounce with other search types
• Result Display: Shows up to 5 geographic results with magnifying glass icon
• Map Integration: Clicking results places markers and centers map

Additional Geographic Services:

• Reverse Geocoding: Uses OpenStreetMap Nominatim API in lib/src/Utils/ReverseGeocoder.ts
• Same Silent Failure Pattern: Reverse geocoder also fails silently (returns empty string)

Impact

• Poor User Experience: Users don't know if geographic search is broken or just no results
• Confusion: Users may think their search terms are invalid
• Inconsistent Behavior: Other search types (items, tags) work while geographic search silently fails
• No Recovery Mechanism: Users can't retry or know to check their connection
• Stale Results: Previous geographic results may remain visible after API failures

Current Test Coverage

✅ Good: E2E test exists for API error handling (cypress/e2e/search/geographic-search.cy.ts lines 189-213)
❌ Gap: Test only verifies app doesn't crash, not user feedback

Comprehensive Solution

Phase 1: User Feedback (Quick Fix)

const searchGeo = async () => {
  try {
    const { data } = await axios.get(`https://photon.komoot.io/api/?q=${value}&limit=5`)
    setGeoResults(data.features)
  } catch (error) {
    console.log(error)
    setGeoResults([]) // Clear any stale results
    toast.error('Geographic search temporarily unavailable') // User feedback
  }
}

Phase 2: Enhanced Error Handling

• Add retry mechanism with exponential backoff
• Implement fallback to alternative geocoding services
• Add loading states for geographic search
• Provide more specific error messages (network vs. server vs. rate limit)

Phase 3: Resilient Architecture

• Cache recent geographic search results
• Add offline geographic search capabilities
• Implement service health monitoring
• Add user preference to disable geographic search

Benefits

• ✅ Immediate User Feedback: Users know when geographic search fails
• ✅ Consistent UX: Matches error handling patterns used elsewhere in the app
• ✅ Clear State Management: Prevents stale results from confusing users
• ✅ Foundation for Improvements: Enables future retry and fallback mechanisms

Testing Updates Needed

• Update E2E test to verify error toast appears
• Add test for stale result clearing
• Test geographic search recovery after network restoration

This issue affects user experience but doesn't break core functionality, making it suitable for next sprint planning.