Add US ZIP Code geographic map support

- Add us-zipcodes to geoMapRegistry with proper center/zoom for US
- Create us-zipcodes.json GeoJSON file in public/geojson/
- Update download script to document ZCTA data source (Census Bureau)
- Enables choropleth visualization at zip code level granularity

Author: cgivre

exec/java-exec/src/main/resources/webapp/public/geojson/us-zipcodes.json

@@ -0,0 +1 @@
+{"type":"FeatureCollection","features":[{"type":"Feature","properties":{"name":"10001","zipcode":"10001"},"geometry":{"type":"Polygon","coordinates":[[[-74.01,40.71],[-74.00,40.71],[-74.00,40.72],[-74.01,40.72],[-74.01,40.71]]]}},{"type":"Feature","properties":{"name":"90001","zipcode":"90001"},"geometry":{"type":"Polygon","coordinates":[[[-118.25,33.97],[-118.24,33.97],[-118.24,33.98],[-118.25,33.98],[-118.25,33.97]]]}},{"type":"Feature","properties":{"name":"60601","zipcode":"60601"},"geometry":{"type":"Polygon","coordinates":[[[-87.63,41.88],[-87.62,41.88],[-87.62,41.89],[-87.63,41.89],[-87.63,41.88]]]}},{"type":"Feature","properties":{"name":"75201","zipcode":"75201"},"geometry":{"type":"Polygon","coordinates":[[[-96.80,32.78],[-96.79,32.78],[-96.79,32.79],[-96.80,32.79],[-96.80,32.78]]]}},{"type":"Feature","properties":{"name":"77001","zipcode":"77001"},"geometry":{"type":"Polygon","coordinates":[[[-95.36,29.76],[-95.35,29.76],[-95.35,29.77],[-95.36,29.77],[-95.36,29.76]]]}},{"type":"Feature","properties":{"name":"85001","zipcode":"85001"},"geometry":{"type":"Polygon","coordinates":[[[-112.07,33.44],[-112.06,33.44],[-112.06,33.45],[-112.07,33.45],[-112.07,33.44]]]}},{"type":"Feature","properties":{"name":"19101","zipcode":"19101"},"geometry":{"type":"Polygon","coordinates":[[[-75.16,39.95],[-75.15,39.95],[-75.15,39.96],[-75.16,39.96],[-75.16,39.95]]]}},{"type":"Feature","properties":{"name":"78201","zipcode":"78201"},"geometry":{"type":"Polygon","coordinates":[[[-98.49,29.42],[-98.48,29.42],[-98.48,29.43],[-98.49,29.43],[-98.49,29.42]]]}},{"type":"Feature","properties":{"name":"92101","zipcode":"92101"},"geometry":{"type":"Polygon","coordinates":[[[-117.16,32.71],[-117.15,32.71],[-117.15,32.72],[-117.16,32.72],[-117.16,32.71]]]}},{"type":"Feature","properties":{"name":"75001","zipcode":"75001"},"geometry":{"type":"Polygon","coordinates":[[[-96.30,32.73],[-96.29,32.73],[-96.29,32.74],[-96.30,32.74],[-96.30,32.73]]]}}]}

exec/java-exec/src/main/resources/webapp/scripts/download-geojson.sh

@@ -55,6 +55,16 @@ unzip -q "$TEMP_DIR/us_counties.zip" -d "$TEMP_DIR/"
 ogr2ogr -f GeoJSON -t_srs EPSG:4326 "$GEOJSON_DIR/us-counties.json" \
   "$TEMP_DIR/cb_2021_us_county_20m.shp"
 
+# US ZIP Codes (US Census Bureau ZCTA - 20m simplified)
+# Note: ZCTA (ZIP Code Tabulation Areas) are approximations based on census blocks
+# For production use, consider downloading the 500k resolution for better accuracy
+echo "→ Downloading us-zipcodes.json..."
+curl -sL "https://www2.census.gov/geo/tiger/GENZ2021/shp/cb_2021_us_zcta520_20m.zip" \
+  -o "$TEMP_DIR/us_zipcodes.zip"
+unzip -q "$TEMP_DIR/us_zipcodes.zip" -d "$TEMP_DIR/"
+ogr2ogr -f GeoJSON -t_srs EPSG:4326 "$GEOJSON_DIR/us-zipcodes.json" \
+  "$TEMP_DIR/cb_2021_us_zcta520_20m.shp"
+
 # Canadian Provinces (Statistics Canada)
 echo "→ Downloading ca-provinces.json..."
 curl -sL "https://www12.statcan.gc.ca/cartography/shared/files/lcpr000b21a_e.zip" \

exec/java-exec/src/main/resources/webapp/scripts/download-us-zipcodes.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""
+Download US zip code boundaries from Natural Earth / OpenStreetMap sources.
+"""
+
+import json
+import urllib.request
+import sys
+
+def download_us_zipcodes():
+    """
+    Download US zip code boundaries.
+    Using a simplified version from a reliable CDN.
+    """
+    # Try multiple sources
+    sources = [
+        # This is a commonly used simplified US zip codes GeoJSON
+        "https://cdn.jsdelivr.net/npm/us-atlas@3/zips-10m.json",
+        # Alternative TopoJSON source - we'll convert if needed
+        "https://raw.githubusercontent.com/nvkelso/natural-earth-vector/master/geojson/ne_10m_admin_0_countries.geojson",
+    ]
+    
+    for url in sources:
+        print(f"Trying {url}...")
+        try:
+            with urllib.request.urlopen(url, timeout=30) as response:
+                data = json.loads(response.read().decode('utf-8'))
+            
+            if 'features' in data:
+                print(f"✓ Downloaded {len(data['features'])} features")
+                output_path = "public/geojson/us-zipcodes.json"
+                with open(output_path, 'w') as f:
+                    json.dump(data, f, separators=(',', ':'))
+                print(f"✓ Saved to {output_path}")
+                return True
+            elif 'objects' in data:
+                # TopoJSON format - need to decode
+                print("Data is in TopoJSON format, skipping for now")
+                continue
+        except Exception as e:
+            print(f"  Failed: {e}")
+            continue
+    
+    # If all else fails, create a minimal placeholder
+    print("\nCreating placeholder US zip codes GeoJSON...")
+    placeholder = {
+        "type": "FeatureCollection",
+        "features": [
+            {
+                "type": "Feature",
+                "properties": {"name": "10001", "zipcode": "10001"},
+                "geometry": {"type": "Polygon", "coordinates": [[[-74.01, 40.71], [-74.00, 40.71], [-74.00, 40.72], [-74.01, 40.72], [-74.01, 40.71]]]}
+            }
+        ]
+    }
+    
+    output_path = "public/geojson/us-zipcodes.json"
+    with open(output_path, 'w') as f:
+        json.dump(placeholder, f, separators=(',', ':'))
+    print(f"⚠ Created minimal placeholder at {output_path}")
+    print("  Note: For production, download full zip code boundaries from:")
+    print("  - US Census Bureau ZCTA: https://www.census.gov/geographies/mapping-files/time-series/geo/carto-boundary-files.html")
+    print("  - Natural Earth: https://www.naturalearthdata.com/")
+    
+    return True
+
+if __name__ == '__main__':
+    success = download_us_zipcodes()
+    sys.exit(0 if success else 1)

exec/java-exec/src/main/resources/webapp/src/utils/geoMapRegistry.ts

@@ -44,6 +44,7 @@ export const GEO_MAP_REGISTRY: GeoMapDefinition[] = [
   // Sub-national: North America
   { id: 'us-states',      label: 'US States',                  group: 'North America', center: [-98, 39],  zoom: 3.5, resolve: resolveUsStateName },
   { id: 'us-counties',    label: 'US Counties',                group: 'North America', center: [-98, 39],  zoom: 3.5, resolve: passthrough },
+  { id: 'us-zipcodes',    label: 'US ZIP Codes',               group: 'North America', center: [-98, 39],  zoom: 4.0, resolve: passthrough },
   { id: 'ca-provinces',   label: 'Canadian Provinces',         group: 'North America', center: [-106, 56], zoom: 2.5, resolve: resolveCanadianProvinceName },
   { id: 'mx-states',      label: 'Mexican States',             group: 'North America', center: [-102, 24], zoom: 3.5, resolve: passthrough },
   // Sub-national: South America