Arah2/.planning/PROJECT.md

# 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

<!-- Shipped and confirmed valuable. -->

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

### Active

<!-- Current scope. Building toward these. -->

- [ ] 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

<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->

- 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

<!-- Decisions that constrain future work. Add throughout project lifecycle. -->

| 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`):
1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

**After each milestone** (via `/gsd-complete-milestone`):
1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---
*Last updated: 2026-10-23 — Phase 3 complete (Mini App Shell + Geolocation): Mini App live on the same Worker ([assets] binding), Rams map + location chain verified on Android/Desktop/browser after 6 in-gate debug rounds (telegram-web-app.js integration; HMAC signature-field erratum)*