From bdc2e9a9f6c3d455b94a6e4aa695382176df2ca5 Mon Sep 17 00:00:00 2001 From: zemion Date: Mon, 6 Jul 2026 14:40:11 +0200 Subject: [PATCH] Sync Repo-README from project files --- Repo-README.-.md | 146 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 Repo-README.-.md diff --git a/Repo-README.-.md b/Repo-README.-.md new file mode 100644 index 0000000..99442e8 --- /dev/null +++ b/Repo-README.-.md @@ -0,0 +1,146 @@ + + +> 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: + +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; 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.