Phase 3.1: Add interactive Folium map with quality-based markers

Features:
- Interactive geographic visualization of charity sites
- Color-coded markers by quality grade (A=green, F=red)
- Marker clustering for performance with large datasets
- Rich popups with site details, contact info, and recommendations
- Filter sites by quality grade (A/B/C/D/F)
- Toggle marker clustering on/off
- Quality grade legend
- Map statistics showing grade distribution
- Centers map on average lat/lng of filtered sites

Technical:
- Uses Folium + streamlit-folium
- Integrates with existing quality scoring system
- Handles sites without coordinates gracefully
- New navigation page: 🗺️ Interactive Map

Makes geographic patterns in data quality visible!

Author: jonero1

data_explorer.py

@@ -17,6 +17,12 @@
 - Added comprehensive validation recommendations page
 - Implemented quality scoring with actionable improvement suggestions
 - Added data quality summary dashboard
+
+Phase 3 Improvements (Interactive Maps & Advanced Features):
+- Added Folium interactive maps with quality-based color coding
+- Geographic visualization of charity sites
+- Cluster markers for performance
+- Site detail popups with quality metrics
 """
 
 import os
@@ -62,6 +68,11 @@
 import json
 from dataclasses import asdict
 
+# Phase 3: Interactive mapping imports
+import folium
+from streamlit_folium import st_folium
+from folium.plugins import MarkerCluster
+
 # Local imports - sys.path setup for module imports
 sys.path.append(os.path.join(os.path.dirname(__file__), 'src'))
 
@@ -1570,8 +1581,181 @@ def display_data_export(sites: List[Dict], organizations: List[Dict]):
                     st.dataframe(preview_df[available_cols], use_container_width=True)
 
 
+# =========================================================================
+# PHASE 3: INTERACTIVE MAPS & ADVANCED FEATURES
+# =========================================================================
+
+def display_interactive_map(sites: List[Dict[str, Any]]):
+    """
+    Display interactive Folium map of charity sites with quality-based color coding.
+    
+    Phase 3.1: Interactive geographic visualization
+    - Color-coded markers by quality grade (A-F)
+    - Cluster markers for performance
+    - Click markers for site details
+    - Filter by quality grade and region
+    """
+    from tackle_hunger.data_quality import calculate_site_quality_score, get_quality_grade
+    
+    st.subheader("🗺️ Interactive Site Map")
+    st.markdown("*Geographic visualization of charity sites with quality scoring*")
+    
+    if not sites:
+        st.info("No sites data available for mapping")
+        return
+    
+    # Filter sites with coordinates
+    sites_with_coords = [s for s in sites if s.get('lat') and s.get('lng')]
+    
+    if not sites_with_coords:
+        st.warning(f"No sites have geographic coordinates. {len(sites)} sites total, 0 with lat/lng.")
+        return
+    
+    st.info(f"📍 Showing {len(sites_with_coords):,} sites with coordinates (out of {len(sites):,} total)")
+    
+    # Quality grade filter
+    col1, col2 = st.columns(2)
+    with col1:
+        grade_filter = st.multiselect(
+            "Filter by Quality Grade:",
+            options=['A', 'B', 'C', 'D', 'F'],
+            default=['A', 'B', 'C', 'D', 'F'],
+            help="Show only sites with selected quality grades"
+        )
+    
+    with col2:
+        show_clusters = st.checkbox(
+            "Enable Marker Clustering",
+            value=True,
+            help="Group nearby markers for better performance"
+        )
+    
+    # Calculate quality scores for all sites
+    sites_with_quality = []
+    for site in sites_with_coords:
+        quality = calculate_site_quality_score(site)
+        if quality['grade'] in grade_filter:
+            site_data = site.copy()
+            site_data['quality_score'] = quality['overall_score']
+            site_data['quality_grade'] = quality['grade']
+            site_data['recommendations'] = quality['recommendations']
+            sites_with_quality.append(site_data)
+    
+    if not sites_with_quality:
+        st.warning("No sites match the selected quality grade filters.")
+        return
+    
+    st.success(f"✅ {len(sites_with_quality):,} sites match your filters")
+    
+    # Calculate center of map (average lat/lng)
+    avg_lat = sum(s['lat'] for s in sites_with_quality) / len(sites_with_quality)
+    avg_lng = sum(s['lng'] for s in sites_with_quality) / len(sites_with_quality)
+    
+    # Create base map
+    m = folium.Map(
+        location=[avg_lat, avg_lng],
+        zoom_start=6,
+        tiles='OpenStreetMap'
+    )
+    
+    # Define colors for quality grades
+    def get_marker_color(grade: str) -> str:
+        colors = {
+            'A': 'green',      # Excellent
+            'B': 'blue',       # Good
+            'C': 'orange',     # Fair
+            'D': 'cadetblue',  # Poor
+            'F': 'red'         # Critical
+        }
+        return colors.get(grade, 'gray')
+    
+    # Add markers (with clustering if enabled)
+    if show_clusters:
+        marker_cluster = MarkerCluster().add_to(m)
+        marker_container = marker_cluster
+    else:
+        marker_container = m
+    
+    for site in sites_with_quality:
+        # Create popup HTML with site details
+        popup_html = f"""
+        <div style="font-family: Arial; width: 250px;">
+            <h4 style="margin:0; color: #333;">{site.get('name', 'Unknown Site')}</h4>
+            <hr style="margin: 5px 0;">
+            <p style="margin: 5px 0;"><strong>Quality Grade:</strong> 
+                <span style="font-size:18px; font-weight:bold; color: {get_marker_color(site['quality_grade'])};">
+                    {site['quality_grade']}
+                </span>
+                ({site['quality_score']:.1%})
+            </p>
+            <p style="margin: 5px 0;"><strong>Address:</strong><br>
+                {site.get('street1', 'N/A')}<br>
+                {site.get('city', 'N/A')}, {site.get('state', 'N/A')} {site.get('zip', '')}
+            </p>
+            <p style="margin: 5px 0;"><strong>Contact:</strong><br>
+                📞 {site.get('publicPhone') or site.get('phone') or 'N/A'}<br>
+                📧 {site.get('publicEmail') or site.get('email') or 'N/A'}<br>
+                🌐 {site.get('website', 'N/A')}
+            </p>
+            <p style="margin: 5px 0; font-size: 11px; color: #666;">
+                <strong>Top Recommendations:</strong><br>
+                {'<br>'.join(site['recommendations'][:3])}
+            </p>
+        </div>
+        """
+        
+        # Add marker to map
+        folium.Marker(
+            location=[site['lat'], site['lng']],
+            popup=folium.Popup(popup_html, max_width=300),
+            tooltip=f"{site.get('name', 'Unknown')} - Grade: {site['quality_grade']}",
+            icon=folium.Icon(
+                color=get_marker_color(site['quality_grade']),
+                icon='info-sign'
+            )
+        ).add_to(marker_container)
+    
+    # Add legend
+    legend_html = '''
+    <div style="position: fixed; 
+                top: 10px; right: 10px; width: 180px; height: 180px; 
+                background-color: white; border:2px solid grey; z-index:9999; 
+                font-size:14px; padding: 10px">
+    <p style="margin:0; font-weight:bold;">Quality Grade Legend</p>
+    <p style="margin:5px 0;"><span style="color:green;">●</span> A - Excellent (90-100%)</p>
+    <p style="margin:5px 0;"><span style="color:blue;">●</span> B - Good (80-89%)</p>
+    <p style="margin:5px 0;"><span style="color:orange;">●</span> C - Fair (70-79%)</p>
+    <p style="margin:5px 0;"><span style="color:cadetblue;">●</span> D - Poor (60-69%)</p>
+    <p style="margin:5px 0;"><span style="color:red;">●</span> F - Critical (&lt;60%)</p>
+    </div>
+    '''
+    m.get_root().html.add_child(folium.Element(legend_html))
+    
+    # Display map in Streamlit
+    st_folium(m, width=1200, height=600)
+    
+    # Display summary statistics
+    st.markdown("---")
+    st.subheader("📊 Map Statistics")
+    
+    col1, col2, col3, col4 = st.columns(4)
+    
+    grade_counts = {}
+    for grade in ['A', 'B', 'C', 'D', 'F']:
+        grade_counts[grade] = len([s for s in sites_with_quality if s['quality_grade'] == grade])
+    
+    with col1:
+        st.metric("🟢 A-Grade Sites", grade_counts['A'])
+    with col2:
+        st.metric("🔵 B-Grade Sites", grade_counts['B'])
+    with col3:
+        st.metric("🟡 C-Grade Sites", grade_counts['C'])
+    with col4:
+        st.metric("🔴 D/F-Grade Sites", grade_counts['D'] + grade_counts['F'])
+
+
 def main():
-    """Main Streamlit application with Phase 1 improvements."""
+    """Main Streamlit application with Phase 1, 2, and 3 improvements."""
     set_page_config()
 
     st.title("🍽️ Tackle Hunger Data Explorer")
@@ -1637,7 +1821,8 @@ def main():
             "Quality Analytics", 
             "Network Graph",
             "📥 Data Export",           # Phase 2: Export functionality
-            "✅ Validation Recommendations"  # Phase 2: Quality analysis
+            "✅ Validation Recommendations",  # Phase 2: Quality analysis
+            "🗺️ Interactive Map"        # Phase 3.1: Interactive map
         ]
     )
 
@@ -1678,6 +1863,9 @@ def main():
     elif page == "✅ Validation Recommendations":
         # Phase 2: Validation recommendations page
         display_validation_recommendations(sites, organizations)
+    elif page == "🗺️ Interactive Map":
+        # Phase 3.1: Interactive map
+        display_interactive_map(sites)
 
     # Footer
     st.markdown("---")