ambek .planning
This commit is contained in:
araharah-executor
@@ -0,0 +1,126 @@
|
||||
# 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)*
|
||||
Reference in New Issue
Block a user