trails/docs/inspirations.md

Inspirations & prior-art research

Durable record of the open-source projects we've studied, what we learned, and which OpenSpec changes each insight spawned. This is the source of truth for acknowledgments: the credit line under each project is the canonical one-liner reused by docs/philosophy.md (Open Source section) and the /about/credits page (see openspec/changes/credits-page/). Update all three together when adding a project.

Research method: shallow-clone the repo, fan out parallel exploration agents over focused areas (data model, integrations, product, ops, community), then synthesize trails-relevant learnings and turn the actionable ones into OpenSpec proposals. Clones live in ephemeral scratch space; this document is what survives.

---

BRouter, bikerouter.de, brouter-web (founding inspirations)

Credit line: BRouter — the routing engine · bikerouter.de — inspiration for the Planner · brouter-web — the web client

The projects that made the Planner conceivable. BRouter is also a runtime dependency (self-hosted routing engine, docker/brouter/). Not "researched" in the sense below — they're in the product's DNA.

---

Organic Maps — reviewed 2026-07-05

Credit line: Organic Maps — inspiration for outdoor-focused map presentation, elevation handling, hiking-time estimation (Tobler), GPX robustness, and privacy-as-proof practices

Offline, privacy-absolutist OSM app (C++, github.com/organicmaps/organicmaps), ~10 years of map-domain experience inherited from MAPS.ME. Different architecture (native offline vs web/federated), but it has solved many problems on our roadmap.

Key learnings (with their source locations)

• Elevation profile hardening (libs/map/elevation_info.cpp): opposite-sign slope-outlier despiking (single-point spikes interpolated out; monotonic climbs never touched), dual raw/threshold-filtered ascent totals (hysteresis accumulation), Douglas-Peucker profile simplification. Their Easy/Medium/Hard track difficulty rating is an unimplemented @todo — a feature we could ship first.
• Hiking ETA (libs/routing/edge_estimator.cpp): Tobler's hiking function for pedestrian speed-by-slope, downhill penalized at 0.35× of uphill, altitude penalty above 2500 m. Also the weight-speed vs ETA-speed split: route choice uses inflated speeds for nice paths; time estimates use realistic ones.
• GPX robustness (libs/kml/serdes_gpx.cpp + fixture corpus in data/test_data/gpx/): timestamp repair (>50% invalid per segment → drop all; else linear interpolation), leading + in coordinates, <rte> imported as tracks, <cmt>/desc merging with dedup, triple-namespace track-color export (Garmin gpxx + gpx_style + osmand) for interop. Their fixture corpus is real files from OsmAnd, gpx.studio, OpenTracks, Garmin.
• Outdoor map presentation (data/styles/outdoors/, generator/osm2type.cpp): a separate Outdoors style that promotes peaks, saddles, springs, drinking water to low zooms; sac_scale + trail_visibility collapsed into just two path grades (difficult/expert) for rendering — two values, big safety payoff. OSM route-relation membership shown on a path's page ("E5, GR5").
• Own the data pipeline (tools/python/maps_generator/, generator/): one batch pipeline from planet file to per-region packs carrying rendering + search + routing + elevation; precompute per-segment elevation at build time instead of querying a DEM live; .poly-file region splitting; category-as-pseudo-language search-trie trick (category IDs indexed as a fake language alongside names).
• Practices: privacy proven by third-party audit evidence published in-repo (Exodus reports) rather than asserted; opt-in email-with-log diagnostics instead of telemetry; excellent docs/PR_GUIDE.md (small-PR norm, LLM-use disclosure); anti-roadmap stance (milestones over a ROADMAP file); root CLAUDE.md with AGENTS.md symlink + nested per-domain CLAUDE.md files; GPS track-recording filter (libs/map/gps_track_filter.cpp: accuracy >250 m rejected, acceleration >2 m/s², bearing-flip rejection, file-backed ring buffer) — reference for docs/ideas/mobile-activity-recording.

Changes spawned

elevation-profile-hardening, gpx-parser-robustness, hiking-time-estimate, poi-index (pipeline pattern + evidence), hiking-foot-profile (the review exposed the trekking-labeled-"Hiking" mismatch).

Explicitly not pursued

Deep-link codec (session URLs cover it), track-color export (nothing renders colors), MWM/offline formats (wrong architecture for web).

---

Endurain — reviewed 2026-07-06

Credit line: Endurain — inspiration for the Journal's activity privacy controls, account export, duplicate handling, and self-hosting operator experience

Self-hosted Strava alternative (codeberg.org/endurain-project/endurain; FastAPI + Vue, AGPL, single maintainer). Overlaps the Journal only; its federation is frontend scaffolding — trails is ahead there.

Key learnings (with their source locations)

• Granular privacy (users/users_privacy_settings/models.py, activities/activity/models.py, apply_visibility_mask()): ~13 independent per-signal hide flags (start time, location, map, HR, power, pace, laps, gear…), per-user defaults stamped at import, per-activity overrides, one server-side mask, one frontend gate component.
• Account export/import (users/users_profile/export_service.py): streaming, memory-bounded ZIP of everything including original uploaded FIT/GPX files; matching import with ID remapping.
• Cross-source duplicate handling (activities/activity/crud.py): same-start-time match → store anyway, flag is_hidden, notify for manual review. Flag-and-review over silent auto-merge.
• FIT parsing quirks catalog (activity_file_import/utils_fit.py, 1,147 lines of fitdecode handling): multi-session files → sliced per-session records, semicircle→degrees, timezone via TimezoneFinder + device-offset fallback for indoor, zero-HR sensor-dropout exclusion, enhanced_* fields preferred, cursor resets across pauses, timestamp_16 rollover. Tests: backend/tests/.../test_utils_fit.py.
• Elevation smoothing convergence (compute_elevation_gain_and_loss): median(6) → moving-average(3) → 0.1 m threshold — independent confirmation that naive delta-summing overstates ascent.
• Gear tracking (gears/): types + retirement + mileage offset, components/consumables with expected_kms wear thresholds, time-based wear for racquets, default gear per activity type.
• Operator experience (docs/getting-started/advanced-started.md, three compose variants incl. Docker-secrets): ~45-variable documented env table; BYO-OAuth-credentials pattern (each self-hoster registers their own provider app). Auth stack is mature (refresh rotation, TOTP, OIDC, API keys, SSRF allowlists).
• Contrasts that validate trails' choices: unofficial password-based Garmin login with unlink-on-expiry (vs our official-API path), polling without webhooks (vs our Wahoo webhooks), no health endpoint/metrics, no changelog, offset pagination. TRADEMARK.md (AGPL code + registered word mark restricting commercial hosting) is an interesting governance read.

Changes spawned

account-export, activity-duplicate-review, fit-parsing-hardening, activity-locations (their feature, our privacy-preserving offline redesign), self-hosting-guide, activity-privacy-controls.

---

wanderer — reviewed 2026-07-06

Credit line: wanderer — a self-hosted, federated trail database; the closest neighbor to the Journal's federated route sharing and proof the ActivityPub-for-trails idea works

Self-hosted federated trail database (wanderer.to, github.com/Flomp/wanderer; AGPL, Go/PocketBase + SvelteKit + Meilisearch + WASM provider plugins). Same route-vs-activity split as trails ("trails" + "summit logs"). The only studied project that has shipped ActivityPub for trail content.

Key learnings (with their source locations)

• Federation is real and Mastodon-interops (db/federation/*.go, db/util/activitypub.go, protocol doc docs/src/content/docs/develop/federation.md with full JSON examples): per-user RSA keys, signed fetch ("authorized fetch"), WebFinger, Follow/auto-Accept, Likes, comments as Note + inReplyTo, summit logs federate as first-class objects. Object model: everything is a plain Note — metrics ride in bespoke tag[] note entries, GPX as a Document attachment (3-photo cap, lossy unit encoding). Interop with trails' Fedify journal is feasible at the social layer; exchanging actual route data would need a wanderer-specific adapter. Their Note-with-attachments shape is why trails render in Mastodon — worth considering a Note-compatible representation alongside structured objects.
• Federation weaknesses to avoid: fire-and-forget delivery (detached goroutine, semaphore(5), no queue/retry — activities lost on transient failures), no inbound dedup/replay defense, no moderation or instance-blocking at all, no shared instance actor, signature verification coupled to X-Forwarded-Path proxy headers. Their SSRF-safe outbound HTTP client (db/util/network.go: private-IP blocking, 30 req/min/origin) is worth copying.
• Discovery at scale (db/util/meilisearch.go, db/routes/search_token.go, web/src/routes/api/v1/search/trails/cluster/): Meilisearch with _geo + precomputed bbox scalars (antimeridian-aware viewport filters); access control enforced at the index layer via tenant tokens (anonymous → public=true; authed → public OR author OR shared-with, minted per session); server-side supercluster clustering where the largest-bbox trails render as polylines and the rest cluster; random-offset sampling for recommendations; remote/federated trails indexed as local stubs so cross-instance content is searchable.
• Trail data model (db/migrations/1747064968_collections_snapshot.go, web/src/lib/models/): polyline + bbox computed server-side on GPX change; stats recomputed from files, never trusted; dual-threshold elevation filter (5 m horizontal anchor / 5 m vertical, raw + smoothed kept — third independent confirmation that naive ascent summing is wrong); optional DEM elevation correction via self-hosted Valhalla height service (gpx.correctElevation()) — an idea trails hasn't considered; all formats (FIT/TCX/KML/KMZ) normalized to GPX at import.
• Product features: ordered trail lists with per-actor view/edit shares; link-share tokens (view/edit) for private content; 9 notification types with per-type web/email preferences; print view with map, elevation profile, scale bar, and QR code (jsPDF) — paper backup for hikes; collection export as ZIP (GPX or JSON, photos + summit logs); hashed long-lived API tokens for third parties; sandboxed WASM provider plugins (Strava/Komoot/Hammerhead — plugins can't open sockets; a host executor injects auth and enforces policy; plugins/README.md is an excellent architecture doc).
• Ops practices: sectioned semver CHANGELOG with GHSA/PR references; boot-time hard failure on missing/default encryption keys; search index treated as rebuildable cache and excluded from backups; explicit AI-assisted-contribution policy in CONTRIBUTING. Cautionary tales: real default secrets committed in docker-compose.yml, no reverse-proxy/TLS setup docs, backup restore only supported within the same minor version.

Changes spawned

federation-hardening (durable Fedify queue replacing the in-process one, replay dedup, instance blocklist, FEDERATION.md), link-share-tokens (revocable tokenized view links for private content).

Changes updated with these findings

route-federation (prior-art section: Note-model contrast, interop verdict, dual-representation consideration, hardening dependency), route-discovery (prior-art section: query-layer access control, clustering/recommendation patterns), self-hosting-guide (no default secrets + boot fail-fast, rebuildable-state backup guidance, restore-version rule). Not yet acted on: per-type notification channel preferences (future notifications delta), print view with QR code, hashed API tokens, Valhalla-style DEM elevation correction.

Explicitly not pursued

PocketBase/SQLite single-binary direction (Postgres+PostGIS gives native geo without a mandatory search sidecar); WASM plugin system (in-app providers are simpler at trails' provider count); Meilisearch itself (PostGIS + SQL covers trails' discovery scale for now).