Alpha stage commit

services/api/README.md

@@ -0,0 +1,76 @@
+# API Service
+
+Purpose: trip planning, route/stage/POI/rule/offline/export endpoints.
+
+MVP implementation should first work with mock providers and fixtures.
+
+Provider interfaces:
+
+- RoutingProvider.
+- PoiProvider.
+- ElevationProvider.
+- WeatherProvider.
+- RulesProvider.
+- DeviceExportProvider.
+
+Recommended backend:
+
+- FastAPI or equivalent.
+- PostgreSQL + PostGIS.
+- Redis/worker for long-running imports/offline pack jobs.
+
+See `schemas/openapi.yaml` and `schemas/database.sql`.
+
+## Implemented MVP
+
+This package currently uses an Express TypeScript API with mock providers, BRouter bikepacking routing, optional OSRM fallback, and optional Overpass POIs. It implements:
+
+- `POST /v1/trips`
+- `POST /v1/routes/plan`
+- `POST /v1/stages/plan`
+- `GET /v1/routes/:routeId/pois`
+- `GET /v1/routes/:routeId/gaps`
+- `GET /v1/rules`
+- `POST /v1/offline-packs`
+- `GET /v1/routes/:routeId/export?format=gpx`
+- `POST /v1/reports`
+
+Run locally:
+
+```bash
+npm -w @pikebacker/api run dev
+```
+
+The default provider mode is `mock`; it uses deterministic fixtures from `packages/shared` aligned with `examples/sample_trip_request.json`. A request can pass `provider: "brouter"` to use BRouter candidate selection or `provider: "osrm"` to use the configured OSRM endpoint. External routing/POI/rules providers return clear setup errors until their adapters and credentials are added.
+
+For `provider: "brouter"`, the API maps Pikebacker profiles to candidate BRouter profiles and selects by Pikebacker suitability score:
+
+- `loaded_gravel`: `gravel`, `safety`, `trekking`
+- `beginner_safe`: `safety`, `trekking`, `gravel`
+- `hardtail_bikepacking`: `gravel`, `mtb`, `trekking`
+- `road_touring`: `trekking`, `fastbike-lowtraffic`, `safety`
+- `ebikepacking`: `trekking`, `safety`, `gravel`
+
+## Environment
+
+```bash
+PORT=8000
+ROUTING_PROVIDER=mock
+POI_PROVIDER=mock
+RULES_PROVIDER=mock
+OSRM_BASE_URL=https://router.project-osrm.org
+OSRM_PROFILE=bike
+BROUTER_BASE_URL=https://brouter.de/brouter
+BROUTER_PROFILE=
+OVERPASS_BASE_URL=https://overpass-api.de/api/interpreter
+```
+
+No API keys are required for mock mode, BRouter public routing, OSRM demo routing, or Overpass public POI lookup. Keep external provider keys in environment variables only. Public routing/POI endpoints are not production dependencies.
+
+To try live OSM POIs:
+
+```bash
+POI_PROVIDER=overpass npm -w @pikebacker/api run dev
+```
+
+Public Overpass instances can time out or reject broad queries. The route planner degrades by returning the route with a warning if POI lookup fails.