Screenshots
Desktop — Split view with day-by-day timeline, contextual alerts, and interactive map.
Mobile — Day-by-day timeline on a phone-sized screen.
Overview
Bike Trip Planner is a bikepacking trip planner with a decoupled architecture: a PHP
backend (API Platform 5 on Symfony 8.1) computes trips through async workers, and two
clients, a Next.js 16 web app and an Expo native mobile app, manage presentation and state.
It imports a route from Komoot, Strava, RideWithGPS or a GPX upload, then builds a
day-by-day roadbook with:
- a fatigue- and elevation-aware pacing engine, with editable stages and rest days;
- a rule-based safety and comfort alert engine (terrain, traffic,
weather, calendar, services);
- accommodation, cultural POI and local event discovery from OpenStreetMap, DataTourisme
and OpenAgenda, and per-stage Open-Meteo forecasts;
- an in-ride nearby-search assistant (no AI);
- GPX / FIT export and read-only share links;
- magic-link accounts with data export and account erasure;
- an MCP server so an AI agent can plan trips on your behalf, under OAuth 2.1 with
revocable access.
See the feature overview, or the rider tutorial
Plan your first trip.
Quick start
git clone https://github.com/vincentchalamon/bike-trip-planner.git
cd bike-trip-planner
make start-dev
The app is available at:
See Getting Started for prerequisites and detailed setup instructions.
Mobile app
Bike Trip Planner has two surfaces on one API: the web app above (discovery,
sharing, planning on a large screen) and a native mobile app for in-the-field
use: offline consultation of upcoming trips, in-ride assistance and push
notifications (ADR-053).
The codebase is an npm-workspaces monorepo:
| Workspace | Role |
|---|
core/ (@btp/core) | Framework-free shared package: OpenAPI-derived types, Zod schemas, Mercure wire types, and the pure SSE reconciliation reducers used by both web and mobile |
pwa/ | Next.js 16 web app |
mobile/ | Expo / React Native app (Android first, iOS later) |
The mobile foundation is documented in
ADR-054 (design system),
ADR-055 (state architecture), and
ADR-056 (Mercure header-auth).
npm install # install all workspaces from the repo root
npm run android --workspace mobile # build & launch on an Android device/emulator (expo run:android)
npm run start --workspace mobile # start the Expo dev server
Documentation
Full documentation is published with MkDocs Material at
https://vincentchalamon.github.io/bike-trip-planner/, and the sources live in docs/.
| Document | Description |
|---|
| Plan your first trip | Rider tutorial: from a route link to an exported roadbook |
| Getting Started | Developer tutorial: requirements, installation, and local setup |
| Features | What the product does, by area |
| Connect an AI agent | Plug an MCP client into your account |
| MCP tools | The tools an AI agent can call |
| Supported route sources | Accepted Komoot / Strava / RideWithGPS / GPX inputs |
| Accommodation types | Logical types, OSM tags, pricing heuristic |
| Alert engine | Every alert code: severity, priority, trigger |
| External data sources | OSM, DataTourisme, OpenAgenda, Wikidata, Open-Meteo, Nominatim |
| Architecture | System overview and the reasoning behind the ADRs |
Contributing
Contributions are welcome! Please read the Contributing Guide before submitting a pull request.
make start-dev # Boot Docker environment
make qa # Run full QA suite (linting, static analysis, formatting)
make test # Run all tests (QA + PHPUnit + Playwright)
License
This project is licensed under the GNU Affero General Public License v3.0.
