## Project **araharah** 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 served as Cloudflare Workers static assets (Workers superseded Pages — see bot/wrangler.jsonc)), 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; the repo has substantial app code: `bot/` (grammY TypeScript worker), `web/` (Vite MapLibre Mini App), `theme/` (Tailwind v4 token package)). **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. ### 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) ## Technology Stack ## Project Maturity - Concept and design-system documents: `DESIGN.md`, `IDEAS.md` - A design-system extension: `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md` (frontmatter-structured design tokens for colors, typography, spacing) - Static HTML UI mockup screens (one `code.html` + `screen.png` per screen) — legacy design reference; the executable code is the `bot/`, `web/`, and `theme/` workspaces - Planning outputs: `.planning/` — not product code; it holds phase plans for the code that now exists ## Languages - HTML 5 — the mockup screens under `stitch_minimalist_route_navigator/*/code.html` are legacy reference; the active UI entry points are `web/` and `theme/gallery.html` - TypeScript — the bot Worker (`bot/src/`) and the Vite Mini App (`web/src/`) - Markdown — design docs (`DESIGN.md`, `IDEAS.md`, `stitch_minimalist_route_navigator/telemetry_rams/DESIGN.md`) ## Runtime - Installed: root `package.json` with npm workspaces `theme`, `bot`, `web`, plus `package-lock.json`. Test config lives in custom harnesses (`bot/test/runner.mjs`, `web/test/runner.mjs`, `theme/scripts/audit.test.mjs`). No `.nvmrc` and no CI config yet. - Mockups run by opening `code.html` directly in a browser (CDN-based dependencies, no local dev server required). ## Frameworks - Tailwind CSS via Play CDN (`https://cdn.tailwindcss.com`) — loaded as a `