# Project pack: wanderer @ decc557

Facts about **wanderer** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> wanderer is a self-hosted trail database. You can upload or draw routes, see distance, elevation and photos, log your own completed hikes, build lists, and follow other people on a federated network. It is built for walkers, runners and cyclists who want to keep their trails.

## Version and source
- Repository: https://github.com/open-wanderer/wanderer
- Pinned commit: `decc55787ba063216bc5068bc1c525c8c0dfd826`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/open-wanderer/wanderer/archive/decc55787ba063216bc5068bc1c525c8c0dfd826.zip
- Official docs: https://wanderer.to/
- Live demo: https://demo.wanderer.to. Shared demo. Don't enter real data.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/open-wanderer/wanderer bespoke-wanderer
  cd bespoke-wanderer
  git checkout --detach decc55787ba063216bc5068bc1c525c8c0dfd826
  # Prepare development requirements and local configuration first.
  cd db
  go run main.go serve
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  curl -O https://raw.githubusercontent.com/open-wanderer/wanderer/main/docker-compose.yml
  # set MEILI_MASTER_KEY and ORIGIN in the file first
  docker compose up -d
  # then open http://localhost:3000
  ```

- Needs: Docker, or Go and Node 22 for development
- Develop: `cd db && go run main.go serve  # and, in another terminal: cd web && npm run dev`
- Stack: typescript, go, svelte (SvelteKit, PocketBase, Meilisearch). Difficulty for a non-developer with an AI: **moderate**. A SvelteKit front end over a PocketBase (Go) back end with a Meilisearch index. Collections and hooks are plain files, and the plugin folder is a gentle way in.

## Customisation points (settings → extend → code)
- **trails-and-lists** [settings]: Upload GPX files, categorise trails and share lists. → `In the app, under Trails, Lists and Profile`
- **privacy** [settings]: Who can see your trails and activities. → `Profile → Privacy settings`
- **plugins** [extend]: Import from other apps and devices. → `plugins/ (for example komoot and hammerhead integrations)`
- **hooks** [code]: Server-side behaviour and endpoints. → `db/hooks/ and db/routes/`
- **web-ui** [code]: Screens and map views. → `web/src`

## Must keep working
- PocketBase migrations in db/migrations. Add new ones; never edit old ones.
- Privacy settings on trails and profiles.
- Federation signatures between servers.

## Staying updatable
Use plugins and hooks as separate files and keep UI changes inside new components.

## Data, costs and safety
- Personal data: **yes**. Stored in: PocketBase data, uploaded GPX files and photos, and a search index (Docker volumes). Start and end points of hikes may reveal your home address. Back up the data folder.
- Service: Meilisearch (included) (required, free): Fast search over trails.
- Service: Valhalla routing (optional) (optional, free self-hosted): Draw routes that follow paths.
- Setting `MEILI_MASTER_KEY` (**secret**: the person enters it themselves, never in chat): Key protecting the search index. Never paste it into an AI chat.
- Setting `ORIGIN`: The address people use to reach wanderer.
- Hiking start points can reveal where you live. Use privacy settings.
- Keep MEILI_MASTER_KEY secret and don't commit it.

---

# Customising wanderer

wanderer is a SvelteKit front end on a PocketBase server written in Go, with simple plugin scripts.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Screens and map components | web/src/ |
| Server hooks, routes and services | db/hooks/, db/routes/, db/services/ |
| Database migrations | db/migrations/ |
| Plugins (imports) | plugins/ |
| Docs | docs/ |
| Docker setup | docker-compose.yml |

## Use the gentlest change first

1. **Settings (no code):** privacy, lists, categories and profile settings.
2. **Extend:** import plugins and the API.
3. **Code:** hooks and Svelte components.

## Recipes

- **New import plugin:** copy `plugins/komoot`, change the calls to the other service and keep the output as GPX plus metadata.
- **New field on trails:** add a migration and the PocketBase collection field, then add it to the trail form and card.

## Running and checking your changes

- Run the db and web dev servers, upload a GPX file and view it on the map.
- Check privacy: view a private trail while logged out.

## Pitfalls

- Don't edit shipped migrations.
- Search results come from Meilisearch. Re-index after bulk changes.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/wanderer/decc557/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/wanderer/decc557/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/wanderer/decc557/r2/SKILL.md)