# 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*