planet/docs/plans/earth-high-precision-boundary-tiles-plan.md

Earth High Precision Boundary PMTiles Plan

Status

Superseded status:

This plan originally treated boundaries as collector-managed source records. The current implementation has moved country boundaries out of the datasource / collector lifecycle. Boundaries are now Earth static rendering assets managed by Operations and Configuration -> Earth Content -> Boundary Precision and /api/v1/earth/boundaries/*. The bundled low-precision GeoJSON is the default fallback, and high precision is an opt-in local PMTiles build.

Historical implementation notes below are retained only as context and must not be used as the current architecture:

• Three standard source collectors now handle real source ingestion: earth_admin0_boundaries, earth_coastline, and earth_claim_lines.
• Each source collector reads endpoint / headers / auth / target_schema=earth_boundary_source from Collector Settings, downloads the configured payload, stores the full artifact under data/earth-boundary-sources/<collector>/<sha256>.*, and writes a hash / feature-count / artifact-path record to CollectedData.
• The backend earth_boundary_tiles item is now a downstream PMTiles builder. It refuses to run until the three source records exist, then skips rebuilds when source / POV policy / build config are unchanged.
• The frontend boundary layer now requires the production pmtiles-mvt provider and no longer falls back to legacy low-precision GeoJSON.
• Generated loose boundary data is ignored by Git and is not the production deployment format.
• Production PMTiles builds require external tippecanoe and pmtiles CLIs; missing tools fail the builder clearly instead of registering fake tile records.

Still required before claiming true one-to-one high precision:

• Replace the repository seed GeoJSON with audited high-precision admin boundary, coastline, and claim-line source packages.
• Run a real geometry preparation step that applies the China POV policy through union / subtract / validity repair before PMTiles creation.
• Build and publish earth-boundaries-china-pov-v1.pmtiles plus its manifest.

Summary

The Earth boundary layer should use one static PMTiles archive containing MVT tiles instead of thousands of loose GeoJSON files. The artifact is POV-specific: earth-boundaries-china-pov-v1.pmtiles has China POV baked in during offline source preparation, and the browser never patches political boundaries at runtime.

Production should serve a single PMTiles artifact through static hosting and HTTP range requests. In development or on machines that have not opted into high precision, missing PMTiles falls back to the bundled low-precision GeoJSON so the Earth base remains usable.

Key Implementation Rules

• Source inputs must be auditable. OSM admin boundaries, coastline packages, and claim-line endpoints are configured through Earth Content boundary precision settings; config/earth-boundary-sources.example.json remains the versioned example template.
• China POV geometry is applied before tiling:
  • Zangnan and Aksai Chin are unioned into China and subtracted from India.
  • Taiwan/Penghu, Diaoyu Dao and affiliated islands, Chiwei Yu, and South China Sea islands are China hover/country features.
  • The South China Sea dashed line is a claim-line layer only; it never consumes Malaysian, Philippine, Vietnamese, or other land polygons.
  • Kosovo is not an independent country surface in this profile; Gaza is a Palestine region.
• PMTiles/MVT layer names are fixed for the frontend:
  • boundary_admin0
  • boundary_disputed_internal
  • coastline
  • claim_line
• The frontend provider is selected from local high-precision preference plus the boundary manifest:
  • tileProvider: "pmtiles-mvt" reads the PMTiles artifact.
  • Missing high-precision preference, missing manifest, or missing PMTiles artifact falls back to low-precision GeoJSON.
• Redis is not part of v1. Static PMTiles plus browser/CDN range caching is the default performance model.

Cleanup And Documentation

• Do not commit generated loose tiles under frontend/public/earth/data/boundaries/ or source downloads under data/earth-boundary-sources/.
• Remove stale generated debug data before production builds; regenerate it only when smoke testing the debug path.
• Keep the high-level plan, backend collector docs, layer style docs, and ops runbook aligned whenever the provider contract changes.
• After implementation changes, provide user-facing operation steps covering source configuration, artifact build/deploy, page verification, and fallback troubleshooting.

Verification

• The Earth boundary build API reports missing source configuration or missing tools clearly, without creating datasource collection records.
• The PMTiles builder fails as not ready when source artifacts exist but tippecanoe / pmtiles are missing.
• Running the PMTiles builder twice returns unchanged on the second run when inputs are stable.
• git add . --dry-run does not include generated loose boundary tiles or source downloads.
• /home/ray/.bun/bin/bun run build passes in frontend.
• Manual Earth checks confirm:
  • PMTiles range requests are issued only for visible tiles.
  • Boundary toggle, hover tooltip, and country highlight still work.
  • PMTiles failure reports a high-precision boundary error; machines without high-precision enabled continue drawing low-precision fallback boundaries.

Assumptions

• "One-to-one" means source-faithful to the selected audited vector source, not hand-tuned to a screenshot.
• The China POV artifact is static and versioned; no runtime region-based POV switching is planned.
• The repository low-precision seed file is retained as the runtime fallback for country boundaries.