26 KiB
26 KiB
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
startappretrieval — 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/startappdeep-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,
sendVenuelocation/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_tollsetc. — 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