Skip to content

FEATURES.md

Latest commit

 

History

History
143 lines (104 loc) · 28.9 KB

FEATURES.md

File metadata and controls

143 lines (104 loc) · 28.9 KB
Raw

OurHike — Feature List (Draft v2)

This translates OurHikeValues.md into concrete features. v1 scope was narrowed on 2026-07-24: keep the first release small, get it in hikers' hands, then grow.

v1 targets replacing two tools: Avenza (what NYNJTC used, now shut down) and FarOut/Guthook (the ATC's current official AT map app, used by most thru-hikers). Revenue from OurHike is meant to help fund the ATC and its affiliated maintaining clubs — the nonprofits that actually build and maintain the trail — so this isn't just a free replacement, it's meant to be a better funding mechanism for them too.

Identity and privacy design is now consolidated in one place: see IDENTITY_AND_PRIVACY.md for how accounts, trail names, the comment-anonymity window, and check-in privacy all fit together, and for the single UserPreferences model that replaced five separate small settings objects.

v1 MVP — Core Map App

Keep this simple. One thing, done well: an offline-capable map app for hikers, built on a downloadable dataset, showing the handful of things thru-hikers actually need mid-hike. Scope grew on 2026-07-28, worth being upfront about: what began as a fully static, no-account v1 now includes real accounts and a live backend too - not because the core map experience below needs them (it still doesn't), but because closures and safety warnings need someone able to verify and moderate them, and building that narrowly would have cost nearly as much as building it for real. See the new "Safety & community contributions" group below, and TECHNICAL_ARCHITECTURE.md's Backend section for the full reasoning.

  • Trail line / route data, downloadable for offline use. Design drafted 2026-07-28: see TRAIL_BLAZE_COLORS.md - the line should render in the real blaze color painted on the trail (already present as a proper coded field in ATC's own side_trails data), not an arbitrary app color, with a neutral fallback where the color is genuinely unknown.
  • Water sources
  • Trailheads & road crossings
  • Shelters & campsites
  • Resupply points (towns, stores, post offices)
  • "You are here" GPS positioning while fully offline. Map controls (locate-me, zoom, scale, legend) detailed 2026-07-28: see MAP_OPTIONS.md - reuses MapLibre's built-in controls plus a hand-built legend, with web vs. mobile UX spec'd separately. The compass button on that same control is detailed 2026-07-28 in UX_CUSTOMIZATION.md - full auto-rotate is real Post-MVP work, flagged there as harder than it looks.
  • Basic search/filter by POI type
  • Light / dark mode, moved into MVP 2026-08-06 (originally split, with prefers-color-scheme auto-detection in MVP and the manual override deferred): light, dark and auto, chosen in Settings, applied to every screen and to the map canvas. Pulled forward because the original split measured the wrong thing - the override is a small amount of code on top of the detection, but a theme is not a small preference; it changes the look and feel of the whole app at once, and auto-detection alone leaves a hiker who keeps their phone dark with no way to ask for a readable paper map in daylight. There is a real outdoor case underneath it too: a phone screen after dark is the brightest object for a mile, and it costs night vision for minutes afterwards. Not an answer to sunlight glare, which wants more contrast rather than less light and stays with the outdoor usability pass - the Settings control says so in its own words. Scope, and the honest limit on the downloaded raster archive, in UX_CUSTOMIZATION.md.
  • Same core experience on phone (iOS + Android, day one) and on the web
  • A minimal first-run flow - a brief value-prop screen, the download zoom/size choice above (nowhere else for that choice to happen first), and a location-permission request timed to when its value is obvious, not blind on launch. Design drafted 2026-07-28: see ONBOARDING.md - deliberately not an account/settings wizard; explicitly checked against this section's own "no heavy signup wall" UX principle below before adding anything past that.
  • Waypoint icon spec (2026-07-25, from Guthook Guides redesign case study — see "UX principles" below): ~8 color-coded POI categories, one accent color per category against a contrasting background, WCAG AA contrast compliance. A concrete, testable spec to design the shelter/water/resupply/etc. icons against, not just "make it readable."
  • Elevation profile, moved into MVP 2026-07-28 (originally scoped Post-MVP under TRIP_PLANNING.md - pulled forward on its own, without the rest of that feature): a full interactive elevation profile chart plus gain/loss for any selected stretch of trail, and a time estimate via Naismith's Rule (a real, established hiking-pace formula, not a custom one). Real competitive weight (FarOut's signature feature) and a genuine safety angle - knowing a big climb is ahead affects pacing and whether to push on before dark (value #4). Accuracy is the whole point, not a detail: sourced from real bulk-downloadable USGS 1-meter DEM data (prd-tnm.s3.amazonaws.com/StagedProducts/Elevation/1m/, the same S3 infrastructure the topo quads already come from, confirmed directly), sampled densely along the actual trail geometry rather than only at the existing half-mile markers - sparse sampling is exactly what makes other apps' gain/loss feel wrong (it misses real small ups-and-downs). Because this comes from a surveyed dataset rather than live phone GPS/barometer, it also avoids the opposite problem other apps have: sensor noise inflating apparent gain when summed over many small steps. The rest of trip planning (bulk multi-day editing, POI-aware planning assistance, the hierarchical Hike/Segment structure) stays Post-MVP as designed - this is just the elevation data and its display pulled forward on its own. Design drafted 2026-08-03: see ELEVATION_PROFILE.md for the phone's ribbon and waypoint lanes - the mile window they cover, and what counts as the climb ahead.

Safety & community contributions, moved into MVP 2026-07-28

Browsing everything above still needs no account - these four items are what actually need Authentication and a live backend, and only these. Each was reviewed against the same bar Elevation was promoted on (real safety weight, not just a nice-to-have), rather than assumed into MVP by default.

  • Accounts. Design drafted 2026-07-28: see AUTHENTICATION.md - Google/Apple/email sign-in, needed so a moderator can be identified and a reporter isn't fully anonymous, not because browsing the map requires one.
  • Community condition reports & moderation, promoted alongside the two features below that reuse its exact verification mechanism - building that mechanism narrowly for just those two would have cost nearly as much as the real thing. Design drafted 2026-07-28: see REPORT_A_PROBLEM.md - all six report types (blow downs, trash, bad hikers, flooding, shelter repair, animals), the moderation queue, and the verification workflow.
  • Trail closures. Design drafted 2026-07-28: see MAP_OPTIONS.md's "Reroutes / closures" section - a real physical hazard (storm damage, washouts), the same weight of argument that moved Elevation into MVP. The rest of Map Options (background tile options, roads/sidewalk-walkability, snap-to-segment) stays Post-MVP. A second source of the same data, drafted 2026-08-09: see ATC_TRAIL_UPDATES.md - the ATC publishes its own closures and detours as prose, written in the same NOBO mile markers the closure model already uses, and the layer converting those to coordinates is already registered. Nine live notices that no OurHike hiker currently sees.
  • Serious warning pins & the wrong-way/off-trail alert. Design drafted 2026-07-28: see HIKER_SAFETY.md - moderator-escalated bear-sighting/dangerous-human/blow-down warnings, and a deliberately conservative wrong-way alert (still the only push notification OurHike sends). The rest of Hiker Safety (the comment-anonymity window, NWS weather integration) stays Post-MVP.

Explicitly deferred, not because they're low-value, but to keep v1 shippable:

  • Trail magic / hiker-to-hiker features
  • Multi-club admin/config tooling
  • Weather integration (design drafted 2026-07-28, see HIKER_SAFETY.md)
  • Any in-app purchases (see business model below)

Business model

  • No purchases, subscriptions, tips, or payment prompts inside the mobile app shell — this avoids the ~15-30% Apple/Google App Store cut, so more of every dollar reaches the trail clubs.
  • Any paid tier, donation flow, or sponsorship purchase lives on the web version only. The mobile app can link out to the web for that.
  • Per value #5, this is about sustainability, not paywalling safety data — core map/POI data stays free everywhere; monetization is additive (e.g., donations, maybe premium convenience features later), never a gate on safety-relevant info.
  • Longer-term intent: revenue should flow toward funding ATC / affiliated maintaining clubs, not just cover OurHike's own hosting costs.
  • The actual pricing structure (tiers, what's gated vs. free, persona-by-persona), design drafted 2026-07-28: see PRICING_MODEL.md - a thru-hike pass (validated against FarOut's own real $74.99 AT guide price), a regional pass for local/heavy users tied to Multi-club support becoming a real feature, a volunteer exemption gated on Volunteering's not-yet-built hour-tracking, and an annual all-access ceiling. The paywall boundary reuses the existing MVP/Post-MVP line throughout - nothing already free moves behind it.

Data sources (decided 2026-07-24, refined 2026-07-24)

  • Trail POI data (centerline, side trails, shelters, campsites, viewpoints, parking, communities): from the ATC's own public GIS map (ArcGIS-hosted: arcg.is/1nqL542, 9 layers cataloged programmatically — see pipeline/) — the same authoritative source FarOut itself uses. The ATC has maintained this data since 1998. Exact redistribution terms still need to be confirmed with ATC directly; the user can help pull the data or make an introduction. Confirmed gap: ATC's data has no dedicated water-source or general resupply layer.
  • Water sources & resupply POIs (filling the gap above): OpenStreetMap tags (amenity=drinking_water, natural=spring for water; shops/post offices/hostels for resupply) plus USGS hydrography (streams/springs) as an approximate water proxy. Both are unverified/approximate, not confirmed-current data — the UI should be honest about that distinction (value #4), not present them with the same confidence as ATC's official facility data.
  • Offline base map tiles: USGS US Topo / National Map raster tiles (apps.nationalmap.gov/downloader), clipped to the corridor — public domain, pre-rendered, the topo format hikers already trust. OpenStreetMap is deliberately not used for the background map (see TECHNICAL_ARCHITECTURE.md for the raster-vs-vector reasoning) — its role is limited to the supplementary POIs above. Scoped to a ~30-mile corridor around the trail and its waypoints only — not full state/regional coverage. This keeps offline downloads small for hikers and hosting costs low (value #8), while still covering everything within a reasonable resupply/support range of the trail.

Platform/tech approach — recommendation

Given the "one codebase" preference, needing phone + web day one, no in-app purchases, and the values around sustainability (#8) and being inheritable by other volunteer-run clubs (#7), my recommendation:

  • Feature gating and experimentation should be built as a cross-cutting platform capability. Start with chapter-aware flags, safe stable defaults, offline-friendly cache evaluation, and clear in-app messaging for any user who sees a preview. This makes every subsequent feature easier to ship and turns product decisions into evidence rather than opinion.

A Progressive Web App (PWA) — a single web codebase (e.g., React/TypeScript) using MapLibre GL JS (open-source map renderer, no vendor lock-in, unlike Mapbox or Google Maps) for the map itself, with offline map data shipped as PMTiles (single static archive files — no tile server to run or pay for, which fits the bounded 30-mile-corridor dataset well). The same codebase is wrapped with Capacitor to produce installable iOS and Android app shells for the app stores, so hikers can still find and install a "real app" — just built from the one web codebase, not a second implementation.

Why this over Flutter or React Native: it draws from the largest possible volunteer developer pool (plain web skills are far more common than Dart or React Native's native-module knowledge), everything in the stack is fully open source with no vendor lock-in, and it sidesteps app-store complexity entirely for anything except distribution — which matters since no purchases happen in the app anyway.

Trade-off to know about: continuous background GPS track-recording (tracking your route while the phone is locked in your pocket) is weaker in a PWA/Capacitor app than a fully native one. Foreground use — open the app, see the map, see "you are here," look up nearby water/shelters — works fine with this approach. If background track-recording becomes a priority later, Capacitor supports native GPS plugins to close most of that gap without a rewrite.

UX principles (inspiration)

Pulled from Zoe Symon's Guthook Guides (now FarOut) redesign case study (2026-07-25) — a UX case study on the app we're most directly positioned against, worth referencing again later. Cross-cutting design guidance, not phase-specific:

  • "Use the app less often, and find information faster when you do." Optimize for quick lookups, not session time/engagement metrics — the opposite of typical app growth goals, and a natural fit with value #1 (hike your own hike): no reason to manufacture engagement.
  • Architect for extensibility from day one. Guthook's original build reportedly lacked this and it limited later feature work — validates our existing instinct (unified POI schema, avoiding AT/NYNJTC-only assumptions per value #7) rather than introducing something new.
  • Community features should be core, not bolted on. Their research found thru-hiking is inherently social — direct validation of the commenting/upvoting/guides items under Community reporting below.
  • Fast, low-friction onboarding — minimal setup before the map is usable, no heavy signup wall blocking time-to-value. Still true for browsing after 2026-07-28's scope change: an account is now needed to submit a report, mark a closure, or moderate one, but viewing the map, water, shelters, GPS, and even closures/warnings themselves stays account-free - see ONBOARDING.md, which only asks for an account at the point a hiker actually tries to contribute, not on first launch.
  • Separate "available" from "owned/downloaded" content clearly — relevant once we have per-section downloads or any paid tier, so users aren't confused about what they already have.
  • A good feature undermined by poor discoverability is its own failure mode. Their route-creation tool was well-liked but hard to find — worth designing findability in explicitly (e.g. for our own trip-planning tools under Extras below), not just building the feature and assuming it'll be found.
  • Process note, not a feature: they ran open-ended surveys across thru-hikers/section-hikers/day-hikers before designing anything — worth doing something similar once NYNJTC's soft launch gives us real users, rather than guessing at priorities.

Post-MVP (Phase 2+)

Grouped by value, for later prioritization — not committed, just not forgotten.

Authentication - moved into MVP 2026-07-28, see the "Safety & community contributions" group above

Google/Apple/email sign-in, email verification, optional MFA, recommended technical approach (Supabase Auth) - full design in AUTHENTICATION.md. Still foundational for the Post-MVP features below that also depend on it (Segments' cross-device sync, Volunteering's club admin access), even though it now ships earlier than any of them.

Community reporting (#2, #4)

The core condition-reporting mechanism (report types, moderation queue, verification workflow) moved into MVP 2026-07-28 - see the "Safety & community contributions" group above and REPORT_A_PROBLEM.md. Everything below is still genuinely Post-MVP - extras on top of that now-MVP foundation, not the foundation itself:

  • Link between hiker reports and official trail-maintenance logs
  • Club data-entry tooling (2026-07-24): local ATC-affiliated clubs need a way to directly add/edit their own shelters, water sources, campsites, and other trail features - not just via the GIS pipeline, which only they (not volunteers at large) can realistically operate. This is the actual mechanism behind "per-club admin roles" below, made concrete.
  • Community submission + upvoting (2026-07-24): beyond condition reports, let community members submit their own POIs/corrections and have other members upvote them - a lightweight trust signal ahead of full maintainer verification. Needs a spam/abuse-resistant design before it ships (value #4 - trustworthy above all - means a wrong upvoted submission is worse than no submission). The corrections half is drafted 2026-08-09: see FIELD_NOTES.md, which resolves the spam concern by removing what would be farmed - nothing aggregates, so recency and reporter type carry the trust signal instead of votes. Submitting a genuinely new POI is still undesigned, and is the harder half.
  • Place-based social commenting, FarOut-style (2026-07-24): comment threads tied to a specific map location, not just structured condition reports. This is the single feature most directly competing with FarOut's actual daily-use appeal, so it matters a lot - but it also sits in the most direct tension with value #9 ("be magical," not just have a magic feature): unmoderated place-based comments are exactly the kind of feature that can tip into the things value #9 explicitly warns against (broadcast/overcrowding pressure, unattended-cache-style posts, oversharing). Needs real moderation/design thought before building, not just a clone of FarOut's comment UI. Design drafted 2026-08-09: see FIELD_NOTES.md - and it answers this bullet by declining most of it. What ships is a dated observation about a place, sorted by recency and attributed by reporter type; there is no thread, no reply and nothing that accumulates, because a conversation is the part that needs moderating and the moderation burden is what the design exists to avoid.
  • User-generated guides (2026-07-24): let hikers compile their own guides/route collections from the underlying data (a bigger, more curated unit than a single comment or report) - e.g. "my recommended water sources for a NOBO thru-hike." Not scoped further yet; revisit once the underlying POI/reporting data model exists to build on.
  • Photos on the waypoint card, including a hiker's own. Design drafted 2026-08-07: see POI_PHOTOS.md. Openly-licensed Wikimedia Commons photos are built and shipping; the rest of that doc is designed and not built — a hiker adding their own photo of a place (private on the device by default, and a memento first, which is why nothing ever asks for one), bulk-importing a trip's photos from their own library and having them matched to waypoints by where and when they were taken, optionally sharing one under CC BY-SA 4.0, and a moderator promoting a shared photo to the default other hikers see. OurHike deliberately never becomes anyone's photo archive: the library keeps the original, the app keeps a thumbnail for the card. Deliberately no votes or leaderboards on that promotion, for the same value #1 reason DATA_NUDGES.md rules them out: the card needs the photo that shows what the place is like now, and a crowd reliably prefers the prettiest sunset.
  • Low-friction data-freshness prompts, encouraging (never requiring) hikers to confirm water/shelter/resupply conditions or check off a resolved report. Design drafted 2026-07-28: see DATA_NUDGES.md - deliberately not a notification of any kind, just visual prominence on the map for data that's gone stale; the actual data-collection mechanism Water Reliability Prediction below already assumes exists.

Hiker safety (#1, #2, #4, #9)

Serious-tier warning pins and the wrong-way/off-trail alert moved into MVP 2026-07-28 - see the "Safety & community contributions" group above. Still genuinely Post-MVP: a configurable anonymity window for comment name/date, and a responsibly-sourced NWS weather-alert relay plus elevation-aware daily conditions. Design drafted 2026-07-28: see HIKER_SAFETY.md.

Water reliability prediction (#4)

  • Predict whether a given water source is likely flowing or dry right now, rather than just showing the last static entry. wikitrail.org's own founding story is literally a hiker hitting a "should be flowing" water source that was dry - this is a real, recurring failure mode of static trail data, not a hypothetical.
  • Likely inputs: historical hiker reports (frequency/recency of "dry" vs "flowing" reports at a source), seasonal/precipitation patterns, and possibly NHD stream classification (perennial vs intermittent) already noted as a data source in TECHNICAL_ARCHITECTURE.md. The "historical hiker reports" input has a real collection design now: see DATA_NUDGES.md.
  • Directly extends value #4's existing "reported 3 days ago vs. confirmed today" idea from a passive timestamp into an actual predictive signal - but the bar is high: a confidently wrong prediction is more dangerous than an honest "unknown," so this should ship after there's enough real report volume to back it, not as a launch feature.

Map display & planning options (#4, #7, #8)

Trail-closure marking/display moved into MVP 2026-07-28 - see the "Safety & community contributions" group above. Still genuinely Post-MVP: user-selectable background tile source and DuckDB-backed snap-to-trail for Segment boundaries. Design drafted 2026-07-28: see MAP_OPTIONS.md - free/live-tile-API options researched directly (USGS's own live service recommended; OSM's raw tiles and Esri's imagery both ruled out for this use, commercial OSM-styled options gated behind a real terms conversation), and an honest walkability signal for trail-to-town road walks.

Trail magic, done right (#9)

  • Point-in-time help requests/offers between hikers — ephemeral, expires automatically, never a persistent pin
  • Explicitly excluded, permanently: any feature for broadcasting unattended caches ("food left at mile X")
  • Volunteer-opportunity surfacing (trail maintenance workdays, club events). Design drafted 2026-07-28 and scoped as v2's second feature 2026-08-06: see VOLUNTEERING.md - grown from a club-side work-project module plus a map layer into the whole volunteer surface, behind a third tab: opting in to contribute conditions, a fourteen-day map of work projects with in-app signup, the Ridge Runner At-Large commitment, logged hours confirmed by a club, and a private record of what someone has contributed. Where the rest of this list is the app being generous around the trail, this is value #9's "generosity toward the trail, not just around it" made into a screen. ROADMAP.md's v2 section is where the scope call lives.
  • Hiker-friendly local business directory
  • Contextual Leave No Trace reminders (e.g., bear-country food storage) tied to location/season
  • No location-sharing or contact exchange without explicit, per-instance consent. This principle's real test case, design drafted 2026-07-28: see COMMUNITY_BUILDING.md - Tramily group-forming, on-demand or ~30-min check-in location sharing, and content-attached "@" mentions, all scoped opt-in/mutual/revocable rather than loosened for this feature.

Data openness & portability (#3, #6)

  • User data export (routes, saved hikes) in open formats (GPX/GeoJSON/CSV)
  • Public read API for trail/POI data
  • Documented, versioned open data schema

Multi-club / inheritance support (#7)

  • Org/club as a first-class data model concept — trails and POIs scoped to a club/region
  • Per-club admin roles
  • Onboarding path for the next ATC-affiliated club with no NYNJTC-specific assumptions baked in
  • How an outside organization actually gets its data in, design drafted 2026-08-03: see SOURCE_REGISTRY.md — the A.T. alone is maintained by thirty clubs plus several agencies, and today all twelve of our layers come from one ATC-run ArcGIS org reachable only by a script that walks a public web map. An organization registers where its data lives (ArcGIS, a file at a URL, an OGC service, a Drive folder — not a database, and the doc explains what to do instead) and a role address to notify when it breaks. Registration is a form; the build input stays a reviewed file in git, so nothing self-service can change a hiker's map without a human merge.
  • Graduates from a future-proofing principle into an actual product surface, per PRICING_MODEL.md: a regional trail pass (local/heavy users, dozens of trails beyond the AT) needs a real multi-trail data model to exist, not just an inheritable schema - this pricing tier is the concrete reason to actually build it.

Fuller onboarding (#1, #4)

  • An optional trail name (a real hiking-culture nickname, not a generic username - local-only by default, a real public identity only once linked to Authentication), a one-line settings mention rather than a walkthrough, and skippable helpful-info tips reusing the waypoint icon spec. Design drafted 2026-07-28, second tier of ONBOARDING.md - waits on Authentication and UX Customization actually existing, since there's nothing yet to onboard a hiker into otherwise.

Community building (#1, #2, #4, #9)

  • Forming a "Tramily" and sharing a planned route, on-demand or periodic location check-ins for safety, and lightweight "@" mentions attached to existing content rather than a chat thread. Design drafted 2026-07-28: see COMMUNITY_BUILDING.md - named directly as this project's biggest privacy-vs-connection tension yet, resolved as a deliberate, carefully-scoped exception (opt-in, mutual, revocable, minimal-retention) rather than a general loosening of the stance Hiker Safety and Data Nudges already took.

UX customization (#1, #4, #5, #7)

  • Persistent light/dark/metric-units preferences, which waypoint types display and at what label density, and auto-rotate (heading-up map orientation). Design drafted 2026-07-28: see UX_CUSTOMIZATION.md - leads with a real planning distinction (persistent settings vs. momentary on-map controls, and app-wide preferences vs. map-specific ones) before the individual toggles, and takes auto-rotate's real platform difficulty (no built-in MapLibre support, a genuine iOS/Capacitor permission dependency) as seriously as the wrong-way alert's.

Extras

  • Elevation profiles per trail/section
  • Trip planning tools (distance, elevation gain, estimated time) — informational, not prescriptive (no streaks/leaderboards, per value #1). Design drafted 2026-07-28: see SEGMENTS.md (the underlying hierarchical Hike/Segment structure - a "segment" means a day to a thru-hiker, a leg between landmarks to a day-hiker) and TRIP_PLANNING.md (waypoint-based day-hike planning, bulk multi-day adjustment, POI-aware planning assistance, and a distance/elevation-gain-and-loss difficulty estimate, honest about what it can't capture). Scoped as v2's first feature 2026-08-05, and spiked before being built: see HIKE_PLANNING.md — the route builder, days rolled up into sections and a whole thru-hike, zero days and resupply stops, a timeline that answers how many days of food a section needs, an auto-generated plan that picks shelters as day boundaries from a target daily time or mileage, and the design for what happens to every later day when today changes. That doc draws the two above together rather than restating either, and ROADMAP.md's v2 section is where the scope call lives.
  • Weather overlay relevant to trail conditions