forked from c-fu/arah2
127 lines
6.9 KiB
Markdown
127 lines
6.9 KiB
Markdown
# 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)*
|