Feature: Interactive map to explore parsed street-sign coverage and identify gaps

[Pascal-ZeGerman]

Goal

Provide an interactive, graphical way to explore the map and identify gaps in coverage so we can evaluate the accuracy and coverage of the Street Sign parsing. The map should allow comparison against other sources (e.g. FreeNYC app) and be hostable on GitHub Pages or a homelab depending on restrictions.

Why

• Visualize parsed street-sign coverage to locate gaps and anomalies quickly
• Cross-check parsed data manually against external sources (FreeNYC)
• Provide an exploratory tool for debugging, QA, and reporting missing/incorrect parsing

Proposed features

• Interactive slippy map (OpenStreetMap tiles) with parsed street-sign locations plotted as points
• Heatmap / density layer to show coverage and gaps
• Filtering by borough, street, date, parsing confidence, sign type
• Side-by-side comparison or overlay of external data source (FreeNYC) for the same area (manual overlay)
• Clickable markers with sign metadata (raw OCR text, parsed schedule, confidence score, source image link)
• Export selected area data (GeoJSON/CSV) for offline analysis
• Optional authentication for homelab hosting; public read-only for GitHub Pages
• Performance considerations for large datasets (tile-based loading, clustering)

Confirmed implementation choices

• Hosting: GitHub Pages (static) — client-side site reads the pre-built index file in the repo
• Index file: src/gps2asp/data/index/graph.json
  • Source URL: https://github.com/Pascal-ZeGerman/GPS2ASP-Resolver/blob/467da9cf0838fd808752783ff7d96ad03dfe521c/src/gps2asp/data/index/graph.json
  • Commit OID: 467da9c
• Data source: pre-processed static index (graph.json). Schema to be validated during development.
• Map provider: OpenStreetMap (Leaflet)
• Address search / geocoding: Default (Nominatim) client-side geocoder
• Priority UI features: Heatmap, Filters (borough/street/date/confidence/sign_type), Search by address
• Area of focus: Whole index
• Update frequency: Manual — rebuild by developer when needed
• Privacy/licensing: None

Acceptance criteria

• Able to view parsed signs on a map and visually identify areas with poor coverage (whole-index support)
• Can manually overlay/check FreeNYC or other sources and highlight mismatches
• Able to export GeoJSON for a selected bounding box
• Index is referenced from src/gps2asp/data/index/graph.json (commit 467da9c)

Implementation notes / recommendations

• Serve a minimal Leaflet frontend from /docs/ that fetches the index file from the repo and provides:
  • point rendering + heatmap
  • client-side filters
  • address search (Leaflet Control Geocoder with Nominatim)
  • export bounding-box GeoJSON download
• If graph.json is large, consider converting to TopoJSON or splitting into tiles during build to avoid shipping a huge single file to clients.
• During development validate the graph.json schema and map fields to GeoJSON Feature properties. Example expected properties (to be confirmed during dev): id, borough, street, parsed_schedule, confidence, sign_type, image_url, timestamp.
• Provide a small proof-of-concept /docs/index.html that demonstrates the basic functionality and references the index file.

Notes / Open items

• Schema validation: developer to confirm mapping from graph.json to map-ready GeoJSON (the file at the link above appears to be a graph structure; developer may need to transform it into point features during build).
• Filesize / performance: if graph.json is large, we should add a build step to produce a compressed/topojson or chunked index for GitHub Pages.