Skip to content
jbrynPublic

About

Plan kayaking trips: distance along real rivers, with weirs, dams and landing places. PHP (Slim) API + Vue 3 client, OpenStreetMap data.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Latest commit

 

History

80 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Downriver

CI

A web app for planning kayaking trips. Pick a river, click where you start and finish, and get the distance along the river, following every bend, with the paddling time and the weirs, dams and landing places on the way.

The Gwda river shown on the map, with its length and numbers of obstacles and access points in the side panel

Status

Work in progress, tracked in the Kayak river tool v1 milestone with one issue per pull request.

Works now Search 15 Polish rivers and show one on the map. Click a start and a finish to measure the section along the river, then drag either end to adjust it. See the estimated paddling time at an adjustable speed, and the weirs, dams, bridges and landing places on the way, listed and marked on the map. Share a trip with a link that reopens the same river, section, unit and speed. Kilometers or miles; light and dark themes; desktop and phone layouts.
Next GPX export; Docker and a public deployment.

How it works

  1. River data comes from OpenStreetMap. A river there is a list of separate pieces. For each river on offer, the pieces and the features along it (weirs, dams, locks, bridges, landing places) are downloaded once through the Overpass API and saved in the repository. The app never waits on an outside service.
  2. The API joins the pieces into one line from source to mouth, refuses rivers whose map data has gaps, and places each feature on the line by its distance from the source.
  3. A section is measured along that line. Both points are snapped to the nearest place on the river, and the distance between them is the length of the line in between.
  4. The web client searches the rivers, draws the chosen one on a Leaflet map with OpenStreetMap tiles, lets you pick a section on it, and shows the section's length, paddling time and features.

The measurements are checked against official river kilometrage from IMGW-PIB, the Polish hydrological service: on 33 stretches between gauging stations, 30 are within the reference tolerance (3%, or 6% on difficult reaches) and 21 within 0.5%.

Tech stack

Part Technologies
API (api/) PHP 8.5.12+, Slim 4, PHP-DI, Guzzle (only for refreshing river data)
Web client (client/) Vue 3, TypeScript, Pinia, Leaflet, Tailwind CSS, Vite
Tests PHPUnit, Vitest, Cypress
Code quality PHPStan (strictest level), PHP-CS-Fixer, ESLint, Prettier
CI GitHub Actions: tests on PHP 8.5, linting, static analysis and end-to-end tests on every pull request

Quick start

You need PHP 8.5.12 or newer with Composer, and Node.js 22 or newer.

git clone https://github.com/jbryn/downriver.git
cd downriver

Start the API (terminal 1):

cd api
composer install
composer start          # http://localhost:8080

Start the web client (terminal 2):

cd client
npm install
npm run dev             # http://localhost:5173

Open http://localhost:5173 and pick a river.

Project structure

api/
  data/          saved river data: the catalogue of rivers and the OpenStreetMap responses
  src/
    Controller/  HTTP endpoints
    Geo/         points and lines on the globe: distances, snapping, sections
    Overpass/    client for the OpenStreetMap Overpass API, with a file cache
    River/       joining pieces into a river, features along it, the catalogue
  bin/           command for refreshing the river data
  tests/
client/
  src/
    api/         typed API client
    components/  Vue components
    composables/ search, theme and shareable-link logic
    stores/      Pinia stores: the selected river and section, and preferences
    utils/       unit conversion, paddling time, feature labels and link encoding
  cypress/       end-to-end tests and their map helpers
docs/            API reference

Development

Command Where What it does
composer test api/ PHPUnit tests
composer lint api/ PHPStan and a code style check
composer format api/ Fixes PHP code style
composer rivers:fetch api/ Downloads fresh river data from OpenStreetMap (see api/data/README.md)
npm run test client/ Vitest unit tests (npm run test:coverage for a coverage report)
npm run e2e client/ Cypress end-to-end tests; both servers from the quick start must be running. npm run e2e:open runs them interactively. Map tiles come from a fixture, not from OpenStreetMap.
npm run lint client/ ESLint
npm run format client/ Prettier

Configuration

Both parts work with their defaults. To change them, copy api/.env.example to api/.env and client/.env.example to client/.env.

File Variable Default Purpose
api/.env APP_DEBUG false Include error details in API error responses
api/.env CORS_ORIGIN http://localhost:5173 Web client origin allowed to call the API
api/.env OVERPASS_OFFLINE true Answer only from the saved river data. Turned off only to fetch new data
api/.env OVERPASS_CACHE_DIR api/data/overpass Where the river data is saved
api/.env OVERPASS_ENDPOINTS two public servers When fetching: Overpass servers to try, comma-separated
api/.env OVERPASS_CACHE_TTL 2592000 (30 days) When not offline: how long saved data counts as fresh
client/.env VITE_API_URL http://localhost:8080 Address of the API

If you run either part on a different port, update the matching variable on the other side.

Documentation

  • API reference: endpoints, responses and errors
  • River data: which rivers are offered, the saved files, and how to add or refresh a river
  • Test fixtures: the reference distances from IMGW-PIB and a river kept as a bad example

Data sources

  • Map data and map tiles © OpenStreetMap contributors, available under the Open Database License.
  • Reference river kilometrage: Instytut Meteorologii i Gospodarki Wodnej – Państwowy Instytut Badawczy (IMGW-PIB).

About

Plan kayaking trips: distance along real rivers, with weirs, dams and landing places. PHP (Slim) API + Vue 3 client, OpenStreetMap data.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages