Mirrored from
/mnt/DATA/git/pikebacker/README.md. Origin:repository. Active tasks and changing state belong in Gitea issues; this wiki page is durable project context.
Bikepacking App Blueprint
This repository is a build brief for a specialized bikepacking application. It is written so a coding agent such as Codex can turn the specification into a working monorepo.
Working name: BikepackPilot.
Core product idea:
Plan and ride multi-day bikepacking routes with confidence: where you can ride, sleep, refill, repair, reroute, and bail out — even offline.
The app should not be a generic route planner. It should combine route planning, daily staging, sleep/water/food logistics, offline use, local rules, local reports, and device export.
Repository purpose
This repository contains:
- product summary and PRD,
- MVP scope,
- technical architecture,
- data-source matrix,
- routing/scoring model,
- offline strategy,
- API and database schemas,
- UX flows,
- risk/legal notes,
- Codex-ready implementation prompts and task breakdown.
Recommended build strategy
Build in this order:
- Planning web app: map, trip request form, route card, stage cards, route-corridor POIs.
- Backend API: route planning adapter, stage planner, POI corridor, GPX export.
- Data foundation: OSM-derived POI import, elevation enrichment, protected-area/rule model.
- Mobile riding app: offline packs, next-critical-thing panel, rerouting, reports.
- Advanced intelligence: bikepacking suitability score, local trust, weather-aware rerouting.
Suggested monorepo shape
apps/
web/ # desktop/mobile web planner
mobile/ # riding/offline app
services/
api/ # backend API
data-pipeline/ # OSM, POI, elevation, rule ingestion
packages/
shared/ # shared domain types, scoring helpers
schemas/ # OpenAPI, SQL, JSON schemas
codex/ # coding-agent prompts and task plan
docs/ # product and architecture documentation
examples/ # sample requests, responses, scoring configs
MVP definition
The first useful version should allow a rider to:
- enter a start/end point, trip dates, bike/load type, daily distance/climb tolerance, sleep preference, and water/resupply constraints;
- receive a bikepacking-oriented route with daily stages;
- see route-corridor water/food/sleep/repair POIs;
- view warnings for long no-water/no-food gaps, uncertain access, steep loaded-bike sections, and missing bailout options;
- export GPX/TCX/FIT-ready route files;
- cache the route, POIs, stage plan, and rule cards offline.
Key differentiator
The app wins by optimizing the whole trip, not only the route geometry:
route + stages + sleep + water + food + repair + rules + weather + bailout + offline
Start here for Codex
Use codex/CODEX_MASTER_PROMPT.md, then execute the tasks in codex/IMPLEMENTATION_TASKS.md.
Current MVP implementation
This repo now includes a runnable TypeScript monorepo MVP:
packages/shared: domain types, deterministic mock fixtures, scoring, stage planning, POI corridor filtering, critical gap detection, GPX export, and offline manifest helpers.services/api: Express API implementing the MVP OpenAPI endpoints with mock providers by default, BRouter bikepacking route candidate selection, optional OSRM fallback, and optional Overpass POIs.apps/web: Vite/React/MapLibre planner UI with OSM raster tiles, route overlay, linked route/elevation profile hover, collapsible planning/export dock, layer controls, bottom route-details drawer, GPX download, offline manifest creation, structured local reports, and offline report queue/sync.apps/mobile: compiled placeholder for offline pack indexing and queued report storage.services/data-pipeline: OSM-like POI fixture normalizer preserving source and attribution fields.
Mock mode requires no external API keys. Non-mock providers intentionally return actionable setup errors until real adapters are configured.
Setup
npm install
npm test
npm run build
Run the API and web planner in separate terminals:
npm run dev:api
npm run dev:web
Default URLs:
- API:
http://localhost:8000 - Web:
http://localhost:5173
Useful commands:
npm run typecheck
npm run fixtures:pois
Environment
Copy .env.example if local overrides are needed. The default MVP uses:
ROUTING_PROVIDER=mockPOI_PROVIDER=mockRULES_PROVIDER=mockVITE_API_BASE_URL=http://localhost:8000OSRM_BASE_URL=https://router.project-osrm.orgOSRM_PROFILE=bikeBROUTER_BASE_URL=https://brouter.de/brouterBROUTER_PROFILE=OVERPASS_BASE_URL=https://overpass-api.de/api/interpreter
Keep commercial provider keys blank in mock mode. Do not commit populated credentials.
The web planner defaults to provider: "brouter". The API evaluates multiple BRouter bicycle profiles for the selected Pikebacker profile and chooses the highest-scored bikepacking candidate. OSRM remains available as an explicit road-biased demo fallback. Public BRouter, OSRM, Overpass, and OSM tile endpoints are development conveniences only; production should use compliant tile hosting and configured or self-hosted routing/POI services.
The first routing editor supports ordered points: start, optional viaPoints, and end. The map can add points from right-click actions, waypoint pins are draggable, and dragging the route inserts a new via point between the nearest existing routing points. BRouter and mock routes expose optional per-coordinate elevationM samples for the web elevation profile; stage cards calculate distance, ascent, and descent from the clipped route geometry when those samples are available. Providers without elevation fall back to aggregate segment ascent/descent only.
Attribution and uncertainty
The web UI, API responses, GPX metadata, and data-pipeline output preserve OSM attribution hooks. Local rules, protected-area warnings, access status, and safety warnings are exposed as confidence-scored advisory information, not guaranteed legal advice.