gis-mapping

Platform Notes

• Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

GIS Mapping (Leaflet-First)

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

• Use for web apps that need Leaflet-first GIS mapping, location selection, map-driven UIs, or geofencing validation. Covers Leaflet setup, optional tile providers, data storage, and backend validation patterns.
• The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

Do Not Use When

• The task is unrelated to gis-mapping or would be better handled by a more specific companion skill.
• The request only needs a trivial answer and none of this skill's constraints or references materially help.

Required Inputs

• Gather relevant project context, constraints, and the concrete problem to solve; load references only as needed.
• Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

Workflow

• Read this SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
• Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
• Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

Quality Standards

• Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
• Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
• Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

Anti-Patterns

• Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
• Loading every reference file by default instead of using progressive disclosure.

Outputs

• A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
• Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
• References used, companion skills, or follow-up actions when they materially improve execution.

Evidence Produced

Category	Artifact	Format	Example
Correctness	Map interaction test plan	Markdown doc covering marker, popup, geofence, and selection scenarios	docs/gis/map-interaction-tests.md
Performance	Map performance budget	Markdown doc covering tile load, marker count, and interaction latency budgets	docs/gis/map-perf-budget.md

References

• Use the references/ directory for deep detail after reading the core workflow below.

Quick Summary

• Leaflet-first mapping for web apps (default engine)
• Optional OpenStreetMap tiles or other providers
• Location selection (marker, polygon, rectangle) + map UI patterns
• Geofencing enforcement with client + server validation (see geofencing.md)
• Performance, clustering, and safe storage of spatial data

Capability Index (Leaflet-First)

Use this index to load only the section you need. Details live in references/leaflet-capabilities.md.

1. Basic Mapping & Visualization (core Leaflet)
2. Spatial Queries (Turf.js)
3. Geocoding (Nominatim or Leaflet Control Geocoder)
4. Buffering & Zone Analysis (Turf.js)
5. Heatmaps & Density (leaflet.heat)
6. Routing & Network Analysis (OSRM / GraphHopper + leaflet-routing-machine)
7. Drawing & Editing (leaflet.draw / Geoman)
8. Measurement Tools (leaflet-measure or custom)
9. Clustering & Aggregation (leaflet.markercluster)
10. Spatial Analysis (Turf.js)
11. Time-Based Analysis (custom + heat)
12. Export & Printing (html2canvas/jsPDF + GeoJSON export)

When to Use

• You need interactive maps for customers, assets, farms, or delivery zones
• Users must select or edit locations on a map
• You must enforce geo-fencing or boundary validation
• You need GIS data display with filters, legends, and clustering

Key Patterns

• Leaflet is the default mapping engine.
• Always include attribution for the chosen tile provider.
• Capture geometry in GeoJSON and validate server-side.
• Use bounding-box checks before deeper polygon math.
• Cluster markers when data is large or dense.
• Store optional tile provider API keys in system settings (e.g., osm_api_key) and load them at runtime.
• Default to terrain tiles (OpenTopoMap) for administrative borders.

Leaflet Standardization (BIRDC)

• Use a shared Leaflet configuration for tile URLs, attribution, and defaults.
• Prefer a shared loader or include pattern so Leaflet CSS/JS is consistent across pages.
• Use the project's canonical Leaflet profile page as the UI reference for layering, interactions, and map controls.

Stack Choices (Frontend)

• Leaflet (default): Lightweight, fastest to implement, best for most apps.
• OpenLayers (optional): Heavyweight GIS controls and projections.
• MapLibre GL JS (optional): Vector tiles, smoother at scale.

Data Model & Storage

• Point: latitude + longitude (DECIMAL(10,7))
• Polygon/Boundary: Store as GeoJSON (TEXT/JSON)
• Metadata: location_label, address, last_updated_at

Recommended formats:

• GeoJSON for portability across JS + backend
• WKT only if your DB tooling depends on it

Map Initialization (Leaflet)

<link
  rel="stylesheet"
  href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css"
/>
<script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

const map = L.map("map").setView([0.3476, 32.5825], 12);
const osmApiKey = window.osmApiKey || "";
const osmTileUrl = osmApiKey
  ? `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?api_key=${osmApiKey}`
  : "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png";

const osm = L.tileLayer(osmTileUrl, {
  attribution: "© OpenStreetMap contributors",
  maxZoom: 19,
});

const terrain = L.tileLayer(
  "https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png",
  {
    attribution: "© OpenTopoMap",
    maxZoom: 17,
  },
);

terrain.addTo(map);

Location Selection Patterns

Marker (Point)

• Single click adds/updates a marker
• Store coordinates in hidden inputs

let marker;
map.on("click", (e) => {
  if (marker) map.removeLayer(marker);
  marker = L.marker(e.latlng).addTo(map);
  document.querySelector("#latitude").value = e.latlng.lat;
  document.querySelector("#longitude").value = e.latlng.lng;
});

Polygon / Rectangle (Area)

Use Leaflet Draw or Geoman. Store GeoJSON geometry.

const drawn = new L.FeatureGroup().addTo(map);
const drawControl = new L.Control.Draw({
  draw: { polygon: true, rectangle: true, marker: false, circle: false },
  edit: { featureGroup: drawn },
});
map.addControl(drawControl);

map.on("draw:created", (e) => {
  drawn.clearLayers();
  drawn.addLayer(e.layer);
  document.querySelector("#boundary_geojson").value = JSON.stringify(
    e.layer.toGeoJSON(),
  );
});

Geofencing (Overview)

Geofencing must be enforced at two levels:

• UI constraint: prevent invalid selections in the browser
• Server constraint: verify boundaries in backend validation

See geofencing.md for full patterns, point-in-polygon checks, and multi-geometry rules.

UI Patterns

• Filters + stats in a side card, map in a large canvas
• Legend to toggle categories (customer groups, territories)
• Clustering when markers exceed ~200

Performance & UX

• Debounce search and map redraw
• Use marker clustering or server-side tiling
• Lazy load heavy layers
• Simplify large polygons for UI display
• Pick a rendering strategy by feature count — see references/rendering-thresholds.md for the full table. Short form:
  • < 200 features: plain markers/SVG
  • 200–2 000 points: Leaflet.markercluster
  • 200–5 000 polygons: preferCanvas: true on the map
  • 2 000–10 000: server-side bbox filtering + per-zoom geometry simplification
  • > 10 000: switch to MVT via Leaflet.VectorGrid or MapLibre/Mapbox GL
  • > 50 000: WebGL overlay (Leaflet.glify, PixiOverlay)
• Return zoom-appropriate geometry from the backend — one simplification tolerance for all zooms is always wrong.

Anti-Patterns (map-specific)

• Loading multi-megabyte GeoJSON at zoom 3 "for completeness" — simplify per zoom.
• Client-side reprojection on every pan — project server-side, deliver EPSG:4326.
• SVG renderer for 10 k+ polygons — switch to Canvas or vector tiles.
• Heatmap under ~200 points — implies density that is not statistically there.
• Two plugins for the same job (e.g. leaflet-draw and Geoman both active) — event collisions, see references/leaflet-plugins.md.
• Leaving L.marker default icon in production — image path breaks when bundled (Webpack/Vite); use a custom icon or shim.

Backend Validation

Always validate coordinates server-side:

• Ensure latitude is between -90 and 90
• Ensure longitude is between -180 and 180
• Enforce geofence boundaries with the same logic as UI
• Load optional tile provider keys (for example osm_api_key) from system settings when building map pages

Privacy & Security

• Location data is sensitive: protect with permissions
• Never trust client-only validation
• Avoid exposing private coordinates without authorization

Recommended Plugins

• Leaflet Draw or Leaflet Geoman (drawing tools)
• Leaflet MarkerCluster (performance)
• Leaflet Control Geocoder (search)
• Turf.js (geospatial analysis)

References

• geofencing.md (sub-skill)
• references/leaflet-capabilities.md
• references/leaflet-arcgis-equivalents.md (index)
• references/leaflet-plugins.md — plugin selection matrix, compatibility checklist, plugin-vs-custom decision
• references/rendering-thresholds.md — feature-count → strategy table, Canvas vs SVG vs WebGL, per-zoom simplification