trails/openspec/specs/poi-index/spec.md

Purpose

A self-hosted POI index that serves OpenStreetMap points of interest for the Planner's POI categories from the instance's own database, replacing the third-party Overpass API. The index is refreshed on a schedule via an OSM extract pipeline and served through a same-origin, rate-limited endpoint with no third-party dependency at request time.

Requirements

Requirement: POI index table

The instance SHALL maintain a planner.pois table of OSM points of interest for the planner's POI categories, storing OSM type and id, category, optional name, centroid point geometry, the element's tags, and import timestamp, indexed for bbox-and-category lookup. Category membership SHALL be derived from the structured tag selectors defined in @trails-cool/map-core, which are the single source of truth for the pipeline filter and import-time classification.

Scenario: Bbox query by category

• WHEN the serving layer queries the index for "drinking water" within a viewport bbox
• THEN all indexed elements whose tags match that category's selectors and whose centroid lies in the bbox are returned

Scenario: Way POIs appear as points

• WHEN an OSM way (e.g. a campground area) matches a category selector
• THEN it is indexed with its centroid as the point geometry

Requirement: Periodic import with atomic swap

The instance SHALL refresh the POI index on a schedule (monthly by default) by filtering an OSM data file to the category selectors, loading the result into a staging table, and swapping it in atomically so serving is never interrupted. The import SHALL abort without swapping when the staging row count falls below 70% of the live table's row count, unless bootstrap mode is explicitly enabled.

Scenario: Refresh replaces data without downtime

• WHEN a scheduled import completes successfully
• THEN the live table reflects the new dataset and no serving request observed an empty or partial table

Scenario: Shrunken dataset refused

• WHEN an import produces fewer than 70% of the live table's rows (e.g. truncated download)
• THEN no swap occurs, the live data stays untouched, and the failure is logged and visible in metrics

Scenario: Regional extract for self-hosters

• WHEN an operator configures a regional extract URL instead of the planet file
• THEN the same pipeline imports that region only

Requirement: POI serving endpoint

The Planner SHALL serve POIs from the index via /api/pois, accepting a bbox and category list, enforcing the same-origin and session checks and the per-IP rate limit that the Overpass proxy enforced, and capping results at 100 per request. The response SHALL provide the fields the client's Poi shape requires (id, coordinates, name, category, tags). POI requests SHALL NOT contact any third-party service.

Scenario: Happy-path query

• WHEN the browser requests two enabled categories for the current viewport
• THEN the endpoint returns matching POIs from the local index with their tags

Scenario: Missing index degrades gracefully

• WHEN the POI table is empty or absent (fresh self-hosted instance)
• THEN the endpoint returns an empty result or a service-unavailable status without errors that break the map

Requirement: Index freshness observability

The instance SHALL expose metrics for index size per category, index age, import job outcome, and serving request counts, and the monitoring stack SHALL alert when the index age indicates a missed refresh.

Scenario: Stale index alerts

• WHEN the index age exceeds the alert threshold (~6 weeks)
• THEN an alert fires identifying the POI import as unhealthy