arah2/.planning/research/FEATURES.md

Feature Research

Domain: Privacy-respecting, Telegram-first GPS navigation (turn-by-turn navigator as a Telegram Mini App, KL metro first) Researched: 2026-10-22 Confidence: MEDIUM-HIGH (platform API details HIGH — verified against official Telegram docs; ecosystem/competitor findings MEDIUM — web sources; KL-local conventions MEDIUM — single-domain sources plus community knowledge, flagged where LOW)

Feature Landscape

The reference products are Waze, Google Maps, OsmAnd, Organic Maps, and (as the Telegram-native analog) bots that send location/venue cards. Because araharah is a driving assistant delivered inside a chat app, the table-stakes set has two layers: (a) what any turn-by-turn navigator owes the user, and (b) what any Telegram experience owes the user. Both layers must be present or users bounce back to Waze — which, notably, is the dominant nav app among Klang Valley drivers, so the comparison is unavoidable.

Table Stakes (Users Expect These)

Guidance & Routing Core

Feature	Why Expected	Complexity	Notes
Destination search with local POI/spelling tolerance	First interaction with the product. Typing "klsentral" or "KLCC" must produce the right place, or the product is dead in 10 seconds	HIGH	Nominatim is exact-ish but poor at typos; Photon (Komoot) is built for fuzzy/autocomplete over OSM and is the opinionated choice. Hard-constrain to KL-metro viewbox. Add a curated local gazetteer for landmark aliases (see KL section).
Current-location origin (geolocation)	No one types their own address; map apps start "from here"	MEDIUM	Telegram Mini App LocationManager (Bot API 8.0+, Nov 2024) triggers the native permission dialog. MUST have graceful fallback: "Send location" attachment button in chat (Telegram reply keyboard request_location) for denied permissions.
Route calculation + map display of route	The literal core value	MEDIUM	OSRM (per IDEAS.md) is fine for fastest-route + alternatives; Valhalla if toll avoidance/eco-cost is needed via costing options (use_tolls, use_highways). Route = polyline + per-step maneuvers + distance/time.
Alternative routes (2–3 shortlist, tappable)	Every consumer nav app shows a route choice screen; showing exactly one route feels broken	MEDIUM	OSRM alternatives=2; present as compact cards (time, distance, headline difference "saves 8 min via DUKE"). Rams-minimal presentation is a feature here — Waze's route screen is cluttered; ours should be 2–3 cards max.
Turn-by-turn maneuver list + next-maneuver banner	Expected shape of driving guidance	MEDIUM	Next-maneuver banner prominent (distance + arrow icon + street name), full list collapsible. Straightforward rendering of OSRM steps.
Missed-turn detection and automatic recalculation	THE signal that an app is "real navigation". Waze's identity is aggressive instant rerouting; users will distrust a navigator that says "you're off route" without fixing it	MEDIUM–HIGH	Detect by snapping GPS track against route polyline; off-route threshold (~30–50m for a few seconds) triggers re-route from current snapped position. Needs map-matching of moving points — modest but easy to get wrong (jitter, tunnels, elevated highways over regular roads in KL).
ETA display + progression	Users sanity-check the ETA constantly ("still 25 min?")	LOW	Remaining time/distance recomputed from current step position; update on each location fix. Google's "glanceable directions" proved the minimal ETA+maneuver+remaining-time triad is the lock-screen pattern users expect.
Voice guidance (spoken turns)	Driving use case; users look at road not screen	HIGH	Web Speech API (speechSynthesis) works in Android webviews but is historically unreliable in iOS WKWebView — iOS Telegram users may get silence. Include mute-by-default, haptic cues on turns (Telegram HapticFeedback), and consider OS-side TTS test on first launch. Telegram sendVoice (bot TTS → opus message) is a platform-native fallback worth designing for.
Speed limit display	ubiquitously expected from Google/Waze on majors	MEDIUM	OSM maxspeed in Malaysia is patchy off federal/highway routes (research shows OSM completeness in MY is uneven). Ship as "where data exists" — display nothing rather than wrong values. Vector tile + server-side maxspeed lookup.
Live location sharing on request (arrival ETA message)	In Telegram context, users send "I'm coming" to whoever is waiting	LOW	Native: sendLocation(live_period) + editMessageLiveLocation — the bot can update a live-location thread with ETA text; zero new UI.
Destination card (venue message) in chat	Before the route, the chat should show WHERE we're going	LOW	Native sendVenue renders a beautiful native card — free table stakes for the Telegram layer of UX.

Telegram Layer (the chat/webview is the OS)

Feature	Why Expected	Complexity	Notes
/start onboarding + global commands (/help, /settings)	Telegram-recommended baseline; the whole product starts here	LOW	/start → 3-sentence explanation + "OK, where to?" with inline-keyboard examples. Global commands are Telegram ecosystem convention.
Destination follow-up flow via chat ("ketik nama tempat")	The bot chat is the search UX in v0 of the funnel	LOW	Free-text → result list (inline keyboard) → "Open navigation" Mini App button with startapp param carrying the destination ID.
Mini App launch with context (destination preloaded)	Users will not re-enter the destination in the webview	LOW (if flows designed together)	Pass destination via ?startapp= deep-link / initData. Verified.
BackButton wired to app state (route list → guidance → search)	Telegram-webview-native navigation; broken/gone BackButton = users swipe the app away entirely	LOW	Telegram.WebApp.BackButton.show()/onClick(); mandatory per Telegram design guideline to mimic native feel.
Theme integration (light/dark)	Telegram Mini App design rule; a nav app opened at night with a white webview chrome is jarring	MEDIUM	Read themeParams, colorScheme, CSS vars; map tiles stay constant; non-map chrome adapts. Rams palette maps well onto dark mode (Matte Black #1A1A1A is already in the palette).
Respect safe areas + fullscreen + landscape	Driving apps are landscape-capable; Telegram 8.0 added full-screen geo tools precisely for this	LOW–MEDIUM	requestFullscreen(), safeAreaInset, disableVerticalSwipes() (prevent accidental minimize while driving), enableClosingConfirmation() during active guidance ("abandon route?" on close attempt).
Haptics on turn alerts	Replaces voice as the "eyes-on-road" cue; platform affordance exists	LOW	WebApp.HapticFeedback.notificationOccurred().

KL/Malaysia conventions

Feature	Why Expected	Complexity	Notes
Landmark-first search ("KLCC", "Sunway Pyramid", "1U", "Imbi", "PWTC")	Local habit: Malaysians navigate to named icons/monuments rather than street addresses; OSM Malaysia completeness is mediocre but major POIs exist	MEDIUM	Curated gazetteer (a few hundred entries: malls, transport hubs, landmarks, "Seputeh"/"Damansara Heights" colloquial district names) layered ahead of generic geocoding. This is the single most KL-specific correctness feature.
Malay/name abbreviation tolerance ("Jalan"↔"Jln", "Taman"↔"Tmn")	Everyday usage; results lists must match even if the user types the short form	MEDIUM	Query normalization layer (synonym/abbreviation expansion) before geocode. Photon does fuzzy-stem matching; abbreviation mapping must be explicit (Jln, Tmn, Jln Persekutuan → FT-prefixed federal routes, "KL"→"Kuala Lumpur").
Toll-aware route option ("avoid tolls")	Klang Valley is dense with tolled highways (Plus, Sprint, LITRAK, DUKE); commuters deliberately avoid them, and toll-free trip prices differ significantly	MEDIUM (easy with Valhalla; clunky with OSRM)	With Valhalla: use_tolls=0 costing. With OSRM: much harder (no clean toll exclusion) — an argument for Valhalla or OSRM dual-profiles. Present as "Toll / Toll-free" toggle, not a settings menu (Rams).
Traffic-relevant display (congestion-aware ETA)	Users compare against Waze; a static ETA in Klang Valley traffic is fiction by definition	HIGH	Honest scoping: v1 without traffic data should show predicted ETA from road classes, but must not pretend it's live. Minimal honest version: re-ETA from observed pace (moving average of user's own speed = free, accurate-to-them, and privacy-friendly). Live public traffic is a differentiator below.
Speed-camera awareness (AES) (v1.x borderline)	Waze popular in MY partly BECAUSE of AES camera pings	MEDIUM but data-dependent	AES camera locations are partially in OSM; scraping/curating is legally gray. Defer — it's the incident-report family, explicitly out of v1 scope (PROJECT.md). Keep on the record for v2 with the reports cluster.

Differentiators (Competitive Advantage)

These are where araharah wins, and every one of them flows from "privacy-respecting Rams bot + Telegram-native" — that is, they are only differentiators because the competitors (Waze/Google) structurally can't copy them.

Feature	Value Proposition	Complexity	Notes
Radical "no tracking" clarity in-product	Users of Waze/Google have no idea what's logged. araharah can SHOW the user the words "we delete your destination when the trip ends, we never associate trips with you" — inside the product, not a privacy policy	LOW	A /privacy command + a 3-line statement on the Mini App landing + a visible "trip ended, deleted" confirmation. Costs almost nothing. Is the brand promise made visible.
Self-erasing guidance state	Server keeps only a short-lived route session token; no history, no profile. Concretely differentiable vs "Google knows everywhere you've been"	MEDIUM	Architecture-level (stateless routing + ephemeral server-side session). Must be stated in the ARCHITECTURE research, but the feature is the visible promise.
Turn-cards in the chat when guidance is backgrounded (the hybrid)	Waze can't message you in a chat; our guidance literally lives where the user already is. Full control: since Telegram webviews pause JS when backgrounded, the bot takes over — sends a chat card with map snapshot + next maneuver + ETA every ~2–3 min or at maneuver points	MEDIUM–HIGH	Server-side guidance session pushes sendPhoto with a static map snapshot (route + position marker) + text turns. Telegram-native sendLocation(live_period) is a zero-build coarse version. This is the marquee differentiator: navigation that lives in Telegram instead of an app overlay.
Rams-minimal UI (calm navigation)	Waze = candy, ads, noise. Google Maps += POI popups. A quiet, high-contrast, icon-first guidance screen is genuinely differentiated and safer while driving (less visual noise = fewer glances)	MEDIUM (design-execution risk, already flagged as #1 in PROJECT.md)	The design system exists; the feature is fidelity discipline: no banners, no distraction, one maneuver at a time.
Home-screen shortcut access to the navigator	"Mini app but behaves like an app" — deep link add to home screen makes araharah launchable without opening a chat (still inside Telegram webview runtime)	LOW	WebApp.addToHomeScreen() (Bot API 8.0+); pairs with homescreen ?startapp deep-links. Cheap, big UX upside.
Opt-in traffic intelligence ("you make the map better")	Privacy-first version of Waze's crowd data: aggregate ONLY opt-in, anonymized, coarse speed pings to weight traffic	HIGH (v2-worthy but a v1 architecture stub helps)	v1 needs only: measure aggregate performance vs OSM speeds server-side for opt-in users, improve ETA. Frame honestly at opt-in time ("help improve routing, 1-min-placeless pings"). This is the seed of v2 incident reports done right.
Trip-sharing via Telegram (this trip only)	Send live-traveling thread to family via the native sendLocation live they already get — no account, no persistent tracking, "share once, expires"	LOW	Wrapping existing Telegram primitives gives a genuinely safety-valuable sharing flow without building any location-stream backend of our own.
Offline-calm fallback via Vector tiles caching (deferred candidate)	KL tunnels/parking; the webview can hold tile caches (WebApp DeviceStorage, Bot API 9.0+) for recent tiles	MEDIUM	Park as v1.x; note mini-app storage is per-origin and size-limited.

Anti-Features (Commonly Requested, Often Problematic)

Deliberately NOT building these is not laziness, it is the product thesis (Rams: "less, but better"), and several are behaviorally toxic in a driving context specifically.

Feature	Why Requested	Why Problematic	Alternative
In-app ads / POI promo cards / sponsored pins	Monetization reflex, Waze does this	Directly contradicts the brand promise; adds attention load to a driving surface; builds a profile per user to serve ads (breaks privacy commitment)	No monetization in v1 (already decided). If ever needed, transparent supporter banner OFF guidance screens or Bot Stars premium, never on the guidance surface
Gamification: points/levels/candy/moods	Waze-heritage feature, social stickiness	Depends on incident-report social structure (out of scope); dopamine loops that reward app-time not safe driving; Rams-violating visual noise	Emotional payoff via product honesty: "you just helped improve this route for everyone" micro-acknowledgment of opt-in pings
Push notification re-engagement ("You haven't driven with us in a while!")	Perfecting DAU metrics	Drive-away behavior for a privacy brand, Rams-minimalism violation, no utility	Telegram itself is opt-in messaging; only transactional messages (guidance cards, cancellation confirmations)
Live incident reports / social commenting (v1)	The emotional appeal of Waze	Huge moderation scope, real-time infra, and dilutes perfecting the navigation core first; explicitly deferred in PROJECT.md Out of Scope	v1: report nothing. Architecture should leave a clean seam for v2 (opt-in aggregated speeds)
Account/sign-up, phone number request, email	Standard SaaS onboarding reflex	Anti-differentiator; everything already exists via Telegram identity	initData validation server-side, that is ALL (already the plan). Never call requestContact()
Fat JSON payload/feature-rich settings menus (route aversion toggles, max speed preferences, per-type avoidance)	Power users request them	Rams principle: hidden decision complexity → settings sprawl; driving apps must not bury the ONE decision (route choice) under options	Three choices max: fastest / toll-free / shorter-dist; everything else derived from defaults
Offline maps (!)	Asked for in every nav product, especially OSM-ecosystem reviewers	Architecturally contrary to a Telegram webview app; tiles+lengthy download UX conflicts with chat-first lightweight promise	Trip-aware tile prefetch in-session (small radius), not offline product
"Chat with an AI assistant" flavor onboarding	LLM-era reflex	Confuses the mental model (navigation is stateful precision, chat is flexible) with token costs and latency	Deterministic, byte-sized onboarding, command-native
Echoing user's location messages into group chats/social features	Attractive for carpool/ETA groups	Crosses individual-user privacy boundary for a feature whose users didn't opt in to being broadcast—must be user-initiated share only	Trip-sharing feature (differentiator above) — always explicitly user-triggered

Feature Dependencies

Telegram search UX (commands, followup flow)
    └─requires──> Destination search (gazetteer + geocode)
                      └─requires──> KL spec: gazetteer + abbreviations, tolls map defaults
    └──enhances──> Venue message (sendVenue)

Mini App launch (startapp deep-link)
    └─requires──> Telegram search UX (you need a destination to carry)
    & ──requires──> LocationManager (geolocation permission, origin)

LocationManager (origin)
    └─requires──> Privacy UX (permission fallback path)

Route calculation
    └─requires──> Destination search ✔ & Current location ✔
    └──enhances──> Speed limit display (routes intersect maxspeed data)

Toll-free routing option
    └─requires──> Valhalla-like costing (or OSRM multi-profile), tile rendering compatible

Turn-by-turn guidance
    └─requires──> Route calculation
    └──requires──> Missed-turn detection ──requires──> Recalculation
    └──requires──> ETA progression
    └──enhances──> Voice guidance ──requires──> TTS support (with fallback), haptics

Backgrounded chat turn-cards (hybrid guidance)
    └─requires──> Turn-by-turn guidance ✔
    └─requires──> Server-side guidance session (ephemeral state) ← privacy-positive
    └─requires──> Static map snapshot renderer (chat photos)

Mini App theming + BackButton + haptics
    └─no feature deps (platform affordances, standalone wiring)

Home-screen shortcut
    └─enhances──> search entry point (deep link with no chat needed)

Opt-in traffic weighting
    └─requires──> Server aggregator + strong privacy UI statement
    └──conflicts-in-v1──> reliability of guidance focus (scope creep risk)

Incident reports / social / gamification
    └─requires──> Opt-in traffic weighting + moderation + groups model (v2 depends on this base)

Dependency Notes

• Guidance requires search + geolocation: the funnel must be built in this order or nothing demonstrates value.
• Recalculation depends on off-route detection, which depends on having route geometry server-side or client-side — the chat-card fallback complicates this (server must re-match); architecture research should treat "guidance session state" as a first-class component.
• Toll-free routing conflicts with OSRM-only choice — the routing engine decision (STACK research) is constrained by this one feature requiring good costing customization.
• Voice guidance conflicts with iOS webview reliability — do not make voice the only modality; haptics + turn-cards carry the same information.
• Privacy features are not feature-isolated: "no tracking" is visible only if the architecture research confirms ephemeral server-side sessions; otherwise it's a lie.

MVP Definition

Launch With (v1)

• /start onboarding + /help — the Telegram UX starts here; zero-cost
• Destination search (Photon/gazetteer, KL-bounded, alias + abbreviation normalizer) — a local POI failure here kills everything downstream
• Venue card in chat (sendVenue) — native, instant trust and clarity that we understood the destination; also "Arrive location" visually in chat
• Mini App launch with destination in startapp — the webview must not make the user re-input
• Geolocation via LocationManager + chat location-send fallback — the origin side of the funnel
• Route draw + alternatives (2–3 cards, time/distance) + Mini App route-choice screen
• Turn-by-turn guidance screen (next-maneuver banner + collapsible full list)
• Missed-turn detection + auto recalculation — the "is this real navigation" test
• ETA + remaining distance progression — minimum viable "live" feel
• Haptic turn cues — cheap, eyes-free, no TTS risk
• BackButton, close-confirmation during active guidance, disable swipe-close — platform behavioral hygiene
• Theme integration (light/dark) + Rams map colors — direct PROJECT.md "design fidelity" requirement
• Home-screen shortcut + deep link startapp retrieval — one call + one param parse, major retained-UX payoff
• Privacy statement visible in-product (Mini App onboard + /privacy) — brand promise made concrete

Add After Validation (v1.x)

• Voice guidance with tested webview TTS + mute-by-default — once driving flow is reliable; important for real point-A-to-point-B daily use
• Backgrounded chat turn-cards w/ static map snapshot + server-side guidance session — this is the flip-side of the hybrid; requires an ephemeral background session design (authentic differentiator, worth planning as its own phase rather than bolting on)
• Live-trip share via sendLocation/editMessageLiveLocation — single feature, high family-safety utility
• Toll-free route toggle (if engine switch justified; Valhalla costing) — matters to many KL commuters; ship once route core is solid
• Speed limit display where OSM has maxspeed — incremental accuracy on majors
• Home-screen tiles caching / modest offline trip radius — stub for future robustness

Future Consideration (v2+)

• Opt-in anonymized crowd speed/aggregated data → smarter ETAs — only after the privacy brand is established and the core trips are proven; the moderation/consent/alert infrastructure for incidents follows this
• Incident reports + broadcasts (already deferred per PROJECT.md) — big scope including moderation
• Regional groups/carpool social (already deferred) — unvalidated hypothesis per PROJECT.md Out of Scope
• Speed-camera (AES) layer — only with legal clarity; lives with the incident family

Feature Prioritization Matrix

Feature	User Value	Implementation Cost	Priority
Telegram onboarding (/start, /help, commands)	HIGH	LOW	P1
KL-accurate destination search w/ aliases	HIGH	HIGH	P1
Mini App launch + BackButton + theme	HIGH	LOW–MED	P1
Geolocation (LocationManager + fallback)	HIGH	MEDIUM	P1
Route + alternatives screen	HIGH	MEDIUM	P1
Turn-by-turn map guidance	HIGH	MEDIUM–HIGH	P1
Missed-turn recalculation	HIGH	MEDIUM–HIGH	P1
ETA progression	HIGH	LOW	P1
Haptic turn cues	MED	LOW	P1
In-product privacy statement	MED (brand-critical)	LOW	P1
Home-screen shortcut	MED	LOW	P1
Venue cards in chat	MED	LOW	P1
Voice guidance	HIGH	HIGH	P2 (v1.x)
Backgrounded chat turn-cards	HIGH	HIGH	P2 (v1.x)
Live-trip share	MED–HIGH	LOW	P2
Toll-free routing toggle	MED–HIGH (KL)	MEDIUM	P2
Speed limit display	MED	MEDIUM	P2
Opt-in traffic weighting	MED (sets v2)	HIGH	P3
Incident reports / social	MED	HIGH	P3 (v2, per scope)

Priority key: P1 = must have for launch; P2 = should have, add when possible; P3 = future consideration.

Competitor Feature Analysis

Feature	Waze	Google Maps	OsmAnd	Our Approach
Missed-turn recalculation	Instant, aggressive; the fastest in class	Instant, calm	Good, slower	Auto-instant; the "is this real navigation" bar
Alternatives on route screen	Up to 3, plus Waze community flavor	2–3 + date/arrival estimates	List form	2–3 quiet Rams cards; time + distance + one-line reason
Voice guidance	Full characterful TTS	Full TTS	Yes (recorded + TTS)	v1.x; mute-by-default, haptic-first, webview-TTS honest fallback
ETA accuracy in KL traffic	Best-in-class (crowd-sourced)	Very good	Weak (no traffic)	v1 honest local self-paced ETA; opt-in aggregate traffic later
Speed limit + cameras	Speed limits everywhere + AES pings (crowd)	Patchy speed limits, no speeds in MY? infrared source dependence	Maxspeed from OSM	Show where OSM is confident; no camera layer in v1 (defer with reports)
Social / incident reports	Core-identity feature (reports, chat, feeds)	Incorporated lightly (accidents/fog/police icons)	Community map editor only	Deliberately absent v1; opt-in crowd-speed is the v2 social replacement, privacy-first
Privacy story	Profiled, sold-into Google ecosystem	Full behavioral pipeline	Excellent (offline-capable, no tracking)	Best-in-class and visible: ephemeral session, stored nothing, stated on every screen entry
Form factor	Native app store install	Native app	Native app	Telegram chat + Mini App — zero install, destination search where conversation lives
Toll awareness	Routed with tolls, options	Good toll toggle	OSM routing tagging support	Expected KL feature; togglable, one prominent toggle

Sources

• Telegram Mini App Web Apps platform docs (core.telegram.org/bots/webapps) — BackButton, LocationManager (Bot API 8.0, Nov 2024), full-screen/safe-area/addToHomeScreen/startapp deep-linking/themeParams/HapticFeedback/DeviceStorage, disable/enable vertical swipes, closing confirmation — verified against the current released API docs — HIGH confidence
• Telegram Bot Features guide (core.telegram.org/bots/features) — commands, global commands (/start,/help,/settings), reply/inline keyboards, sendVenue location/venue messages, live location + editMessageLiveLocation, privacy mode — HIGH confidence
• Waze vs Google Maps comparisons 2025–2026 (ZDNet 2026-07, PCMag 2026-07, USA Today 2025-07) — rerouting-aggressiveness, speed-limit display behavior, Waze popularity with drivers — MEDIUM confidence (third-party review articles)
• OSM Malaysia quality studies (ResearchGate "Quality of OSM in Malaysia" preliminary assessment) — OSM completeness in MY described as "...good relative positioning in road features, but still poor in terms of completeness (POI coverage)" — MEDIUM-HIGH confidence (peer-reviewed-adjacent research)
• Telegram live locations blog (telegram.org/blog/live-locations) — live-location primitive behavior — HIGH confidence
• Routing engine capability notes (GitHub OSRM/Valhalla issues + ecosystem articles) — OSRM does not have native toll-exclusion costing; Valhalla costing supports use_tolls etc. — MEDIUM confidence (engineer-sourced, not yet doc-fetched)
• Domain knowledge / training-data reasoning (flagged LOW, verify at phase research): webview TTS iOS reliability (WKWebView speechSynthesis quirks), exact OSM maxspeed completeness levels per KL arterial, exact AES camera data availability in OSM — LOW confidence, needs phase-specific verification before planning voice/speed features

---

Feature research for: Privacy-respecting Telegram-first GPS navigation app (ararahah, KL metro) Researched: 2026-10-22