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:

1. Planning web app: map, trip request form, route card, stage cards, route-corridor POIs.
2. Backend API: route planning adapter, stage planner, POI corridor, GPX export.
3. Data foundation: OSM-derived POI import, elevation enrichment, protected-area/rule model.
4. Mobile riding app: offline packs, next-critical-thing panel, rerouting, reports.
5. 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:

1. enter a start/end point, trip dates, bike/load type, daily distance/climb tolerance, sleep preference, and water/resupply constraints;
2. receive a bikepacking-oriented route with daily stages;
3. see route-corridor water/food/sleep/repair POIs;
4. view warnings for long no-water/no-food gaps, uncertain access, steep loaded-bike sections, and missing bailout options;
5. export GPX/TCX/FIT-ready route files;
6. 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=mock
• POI_PROVIDER=mock
• RULES_PROVIDER=mock
• VITE_API_BASE_URL=http://localhost:8000
• 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

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; providers without elevation show aggregate 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.