# 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

```text
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:

```text
route + stages + sleep + water + food + repair + rules + weather + bailout + offline
```

## Start here for Codex

Use [`codex/CODEX_MASTER_PROMPT.md`](codex/CODEX_MASTER_PROMPT.md), then execute the tasks in [`codex/IMPLEMENTATION_TASKS.md`](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

```bash
npm install
npm test
npm run build
```

Run the API and web planner in separate terminals:

```bash
npm run dev:api
npm run dev:web
```

Default URLs:

- API: `http://localhost:8000`
- Web: `http://localhost:5173`

Useful commands:

```bash
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.