Sync Repo-README from project files
146
Repo-README.-.md
Normal file
146
Repo-README.-.md
Normal file
@@ -0,0 +1,146 @@
|
||||
<!-- codex-wiki-sync:28f4f0f76264adaa02719d06 -->
|
||||
|
||||
> 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.
|
||||
Reference in New Issue
Block a user