araharah

What This Is

A privacy-respecting GPS navigation app delivered through Telegram: a waze-like route navigator, but Telegram-first instead of an app store install, built on OpenStreetMap data, and designed to Dieter Rams' principle of "less, but better". Users search a destination (e.g. "KLCC") with the bot, tap into a Telegram Mini App (webview hosted on Cloudflare Pages), and receive live route guidance while driving. First users are in the Kuala Lumpur metro area.

Reference design docs: DESIGN.md (design philosophy), IDEAS.md (vision + stack), stitch_minimalist_route_navigator/ (4 UI mockup screens), and .planning/codebase/ (codebase map; current state is design-only, no app code).

Core Value

A user finds a local destination via Telegram and gets there with reliable turn-by-turn guidance — tracked by nothing beyond what they explicitly opted in to.

Requirements

Validated

(None yet — no app code exists; project is greenfield-brownfield hybrid with design assets only)

Active

User can open the araharah Telegram bot and start the app (/start, menu)
User can search a destination by query and get a matching local address/POI
User can open the Telegram Mini App (Cloudflare Pages webview) from the bot
Mini App obtains the user's current location
User sees a chosen route (or short list of routes) to the destination
User receives live guidance while driving (in-app live map when foregrounded; chat turn-cards / map snapshots when backgrounded — hybrid)
The experience visually matches the Telemetry Rams design system ("design fidelity" — flagged as the top risk)

Out of Scope

Incident reports (/accident, /traffic, /hazard + broadcasts) — navigation first; reports ship after the core works
Gamification, points, leaderboards — depends on reports; deferred with them
Regional clusters via Telegram groups — unvalidated social hypothesis
Voice-to-text reporting, offline mode, anonymized public API — future ideas
Push notifications infra beyond Telegram chat (Resend email etc.) — Telegram itself is the channel
Payment/monetization nothing planned

Context

Telegram bot is the primary UX: command menu, destination search, Mini App launch. Mini App should be a proper Telegram WebApp (Telegram WebApp JS API).
OSM ecosystem: OpenStreetMap data (geocoding must understand KL landmarks like "KLCC"), routing (Valhalla — chosen over OSRM for free-first + native toll-free costing), tiles (OpenFreeMap, replacing Maptiler), hosting on Cloudflare Workers with static assets.
Privacy stance chosen: persistent storage only for what users opt in to reports (later), opt-in anonymized telemetry for traffic weighting. Nothing stored without explicit consent.
Region: KL metro first — local geocoding quality is a v1 correctness factor.
Design system "Telemetry Rams": colors (Signal Orange #EB8008, Functional Red #ED3F1C, Olive Green #736B1E, Soft Beige #D9D2C6, Matte Black #1A1A1A), Helvetica Neue/Inter, 8px grid, line icons, Rams motto. Mockups live in stitch_minimalist_route_navigator/ (HTML + Tailwind CDN, single-file).
Known quality risk: turning single-file mockups into a real frontend without losing the Rams look; user explicitly flagged design fidelity as the most likely sink for v1.

Constraints

Platform: Telegram bot + Telegram Mini App (WebApp API) — the webview flow is the product; no independent mobile app in v1
Hosting: Cloudflare Workers with static assets (research finding: Cloudflare now directs all new projects to Workers, not Pages) — one wrangler project serves Mini App statics + /telegram/webhook + /api/*
Free-first infra: every service must be open-source or genuinely free-tier (verified stack: grammY, MapLibre GL, OpenFreeMap, Valhalla, Photon — all $0); no paid APIs. Only infrastructure cost candidate is a small VPS for Valhalla + Photon; Oracle Cloud Always Free is the zero-cost option with a reliability asterisk
Privacy: no location history / profiles stored without explicit opt-in; opt-in only telemetry
Region: KL metro tuning for v1 (geocoding, POI search)
Design: must match Telemetry Rams design system; Rams values are non-negotiable per DESIGN.md
Ops appetite (implied): IDEAS.md lists RabbitMQ, Prometheus/Grafana, Neon, Resend — treat as future/aspirational; v1 should prefer the minimal set of services that the core value actually needs (final choice deferred to research)

Key Decisions

Decision	Rationale	Outcome
Routing engine = Valhalla (replaces OSRM)	User wants free as much as possible; both are free OSS, but Valhalla natively supports toll-free routing (`use_tolls` costing), elevation, and localization — unlocks the KL commuter table-stakes feature	— Pending
Free-first infra mandate	User priority: paid APIs are out; stack is all-OSS/free-tier; VPS (optionally Oracle Cloud Always Free) hosts Valhalla + Photon	— Pending
Navigation-only v1 (no incident reports)	Prove the nav core before social mechanics; user walkthrough was pure navigation	— Pending
Privacy = opt-in telemetry only	"Privacy-respecting" is the brand promise; storage follows explicit consent	— Pending
KL metro first	Local landmark search quality depends on regional tuning	— Pending
Telegram Mini App (not plain web link)	Needs user position, back button, tight Telegram context	— Pending
Hybrid guidance: live map in-app + chat turn-cards when backgrounded	Battery + Telegram-context UX; matches walkthrough and mockups	— Pending
Design fidelity guarded as top risk	Stated as most likely to sink v1; deserves early design-system phase	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

Requirements invalidated? → Move to Out of Scope with reason
Requirements validated? → Move to Validated with phase reference
New requirements emerged? → Add to Active
Decisions to log? → Add to Key Decisions
"What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

Full review of all sections
Core Value check — still the right priority?
Audit Out of Scope — reasons still valid?
Update Context with current state

Last updated: 2025-10-25 — v1 MILESTONE COMPLETE (all 7 phases): arah² is live and privately launched — search, routes, guidance, turn-cards, privacy-audited (7/7 live CLEAN), budget-clean ($0), device-matrix walked, known-limitations shipped. Deferred: battery measurement (v1.x), ALT landmarks (v1.x), repo public flip + launch distribution (user acts)

7.0 KiB Raw Blame History