# arah²
A privacy-respecting, Telegram-first GPS navigator — a waze-like route navigator delivered through a Telegram bot and Mini App instead of an app-store install, built on OpenStreetMap data, and designed to Dieter Rams' "less, but better." First users are in the Kuala Lumpur metro.
The Telegram bot is **arah2bot**. The product is live — a private beta with real drivers in KL: open [@arah2bot](https://t.me/arah2bot), send `/cari KLCC`, open the venue card's Mini App button, and follow live turn-by-turn guidance. The app is served from .
---
## Overview
arah² is an npm-workspaces monorepo with five packages:
| Package | Name | What it does |
|---|---|---|
| `theme/` | `@araharah/theme` | The Telemetry Rams design system as a Tailwind v4 CSS-first token package. Every color, spacing, type, and radius value in the project is defined once in `theme/src/tokens.css` and compiled to `theme/dist/rams.css`. Also ships the MapLibre basemap style `theme/basemap/liberty-rams.json` plus gallery/audit/screenshot tooling. |
| `bot/` | `@araharah/bot` | A [grammY](https://grammy.dev) Telegram bot running on a Cloudflare Worker. It serves the `/telegram/webhook` route, five JSON API routes, keeps TTL-only chat sessions in Workers KV, loads the road graph from an R2 bucket, and pushes turn cards to chat from a scheduled cron tick. It also serves the Mini App's static assets through a wrangler assets binding. |
| `web/` | `@araharah/web` | The Telegram Mini App: a MapLibre GL navigation shell built with Vite. Owns the three-source location acquisition chain, the in-app destination search UI, route rendering, turn-card guidance replay, an in-memory session store, and the Telegram WebApp integrations (theme slots, BackButton, safe-area insets). |
| `search/` | `@araharah/search` | The shared, dependency-free destination-search module: the JUPEM-derived Malay abbreviation table as editable data, a symmetric normalizer, a Damerau (OSA) residual scorer with disjoint tiers, and the curated KL gazetteer with locals' aliases — imported by the bot, the Mini App, and the search-quality corpus runner. |
| `routing/` | `@araharah/routing` | The shared, dependency-free routing data plane: a CSR road graph with snap-to-graph, A* search, and polyline6 codecs. Engine A runs it Worker-side over the R2-hosted graph (`/api/route`); the fixture source (15 committed KL golden pairs) and the route-quality corpus runner live alongside it. |
The Worker is the single origin. It answers `/api/*` and `/telegram/*` itself (`run_worker_first`) and serves everything else out of `web/dist`.
```mermaid
graph TD
U["Telegram client — arah2bot chat + Mini App webview"]
W["Cloudflare Worker — araharah-bot"]
KV[("Workers KV — TTL-only records: sessions 900s, pins 300s, guidance 7200s")]
R2[("R2 — road-graph binary, one GET per cold isolate")]
TG["Telegram Bot API"]
APP["Mini App assets — web/dist via ASSETS binding"]
MAP["MapLibre GL — Rams basemap, OpenFreeMap tiles"]
THEME["@araharah/theme — tokens.css + liberty-rams.json"]
U -->|"POST /telegram/webhook (secret-token header)"| TG
TG --> W
U -->|"GET Mini App"| APP
APP --> W
W -->|"venue card, pin keyboard, turn cards"| TG
APP -->|"POST /api/session — initData HMAC"| W
APP -->|"GET /api/location — Bearer token"| W
APP -->|"POST /api/route — Bearer token"| R2
W --> KV
W -->|"cron */2 → turn cards"| TG
APP --> MAP
THEME -.->|"inlined at build time"| MAP
THEME -.->|"dist/rams.css"| APP
classDef telegram fill:#EB8008,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
classDef worker fill:#1A1A1A,stroke:#EB8008,stroke-width:2px,color:#F7F0E3
classDef storage fill:#D9D2C6,stroke:#1A1A1A,stroke-width:2px,color:#1A1A1A
classDef web fill:#F5EDE0,stroke:#736B1E,stroke-width:2px,color:#1E1B14
class U,TG telegram
class W worker
class KV,R2 storage
class APP,MAP,THEME web
```
---
## Installation
Clone the repository and install workspace dependencies:
```bash
git clone http://gitmirah:3000/c-fu/arah2.git
cd arah2
npm install
```
Requires Node.js and npm (no version is pinned in the repo — use a current LTS; the corpus runners rely on Node's native TypeScript type-stripping). Wrangler handles Cloudflare authentication on first use via `wrangler dev` / `wrangler deploy`.
For the bot's local secrets, copy the example file and fill it in:
```bash
cp bot/.dev.vars.example bot/.dev.vars
```
`bot/.dev.vars` is gitignored and must never be committed. It holds `BOT_TOKEN` (from [@BotFather](https://t.me/BotFather)), `WEBHOOK_SECRET`, and `WEBHOOK_URL` (full origin; `set-webhook.mjs` appends `/telegram/webhook` if only an origin is given).
---
## Quick start
1. **Build the design tokens and the Mini App.** `theme/dist/rams.css` is an input to the web build, so it must exist first.
```bash
npm run build
```
2. **Run everything locally.** Builds the theme, then starts the Worker on port `8787` with `--local`, serving `/telegram/webhook`, the `/api/*` routes, and `web/dist`.
```bash
npm run dev
```
3. **Iterate on the Mini App alone** with Vite on port `5173` (`strictPort`), for map/UI work that doesn't need the bot:
```bash
npm run web:dev
```
---
## Quickstart: clone → production (your own bot, your own Cloudflare)
The concise path. Full detail lives in [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md); local development in [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md).
**1. Create the bot** — in Telegram, open [@BotFather](https://t.me/BotFather):
- `/newbot` → pick a name + username → copy the **bot token**
- `/setuserpic` → upload `assets/logo_arah2.png` (the bot's avatar)
- Bot Settings → **Main Mini App** → set your future production URL (you'll fill the real one in step 4; BotFather's app *name* is what Telegram shows in the mini-app header)
**2. Clone + install**
```bash
git clone
cd arah2 && npm install
cp bot/.dev.vars.example bot/.dev.vars
```
**3. Fill `bot/.dev.vars`** (gitignored — never commit):
```
BOT_TOKEN=
WEBHOOK_SECRET=
WEBHOOK_URL=https://.workers.dev
MINI_APP_URL=https://.workers.dev
```
**4. Deploy to YOUR Cloudflare** (free plan — `$0`):
```bash
npx wrangler login # browser auth, once
npm run build # theme tokens → web/dist
npm run deploy # theme → web → worker + assets + webhook + commands
```
**5. Provision the road graph** (engine A's routing data — R2, also free):
```bash
npx wrangler r2 bucket create araharah-graphs
node routing/scripts/upload-road-graph.mjs # builds + uploads the KL graph, round-trip verifies
```
**6. Register the bot surfaces** (usually already done by `npm run deploy`, re-run to be sure):
```bash
node bot/scripts/set-webhook.mjs # arms the webhook (+ /telegram/webhook path)
node bot/scripts/register-commands.mjs # /help /privacy /cari in every command scope
node bot/scripts/set-menu-button.mjs # the menu button opens the app ("arah²")
```
**7. Verify** — the canaries (read-backs, nothing trusted blindly):
```bash
npm run privacy-audit -- --live && npm run budget-audit -- --live
```
Then in Telegram: restart the client → open the bot → `/cari KLCC` → venue card → **OPEN** → the map routes. Done: your own private navigator, $0/month.
> **Permission notes:** the Cloudflare token (optional, only for the audit `--live` probes) needs Account → Workers KV Storage → **Read** only. The bot itself needs no special Telegram permissions; `/setprivacy` default (off) is correct — the bot never reads non-command messages.
---
## Future enhancements & milestones
**v1.x (next milestone):**
- **ALT landmark preprocessing** — routing backend v2: fixes the cross-metro CPU class while staying $0 (measured decision: short KL reroutes are in-budget today)
- **WASM-router track** — fully client-side routing in the webview (origin+destination never touch a server; static-hosted; the fork-perfect endgame)
- **Battery measurement** — the <10%/hr guidance-drain record (deferred from launch)
- **Bitmap map snapshots** in minimized chat turn-cards (needs a rasterizer in the $0 stack)
- **Voice guidance** · **live trip share** (`sendLocation(live_period)`) · **toll toggle** · **speed-limit display** — the REQUIREMENTS deferred table
**v2 (post user-validation):**
- Incident reports + community layer, gamification, traffic-weighted ETAs — per the original vision doc ([IDEAS.md](IDEAS.md))
**Core concepts** (the privacy law, backend ladders, session flow) are documented in [docs/CORE-CONCEPTS.md](docs/CORE-CONCEPTS.md).
---
---
## Usage
### Talking to the bot
The bot answers in English and Bahasa Melayu. Commands are registered into Telegram's persistent menu by `npm run bot:commands`, which derives its descriptions from `bot/src/i18n/strings.ts` so the menu and the replies cannot drift.
| Command | Alias | Behaviour |
|---|---|---|
| `/start` | `/mula` | One-sentence introduction to arah² and its privacy posture. |
| `/help` | — | Lists the commands that exist and points at the known-limits record. |
| `/privacy` | `/privasi` | Names exactly what is stored (user id, chat id, language, ~15 min) and exactly what is never stored (location, routes, trip history, profile). |
| `/cari` | `/search` | Searches the curated KL gazetteer (`/cari KLCC`) and replies with **one** native venue card (`sendVenue`) carrying an OPEN IN ARAHARAH Mini App button plus 2–4 alternates as callback buttons. Out-of-area queries get an honest refusal that names the v1 area, never the query text. |
### The live flow, end to end
1. **Search.** `/cari ` normalizes and scores the query against the KL gazetteer (`@araharah/search`); the best hit ships as a venue card with deep link `MINI_APP_URL/?dest=`.
2. **Open the Mini App.** The webview reads `?dest=` from `location.search`, preloads the destination, and mints a session by posting the verbatim `Telegram.WebApp.initData` string to `/api/session`.
3. **Acquire a starting point.** The three-link location chain (`web/src/location/chain.ts`) tries **Telegram → WebView → chat pin**, in that locked order.
4. **Route.** The app posts the origin and destination to `/api/route`; the Worker's router (`bot/src/routing/worker-router.ts`) loads the R2-hosted CSR graph once per cold isolate, snaps, and runs A* (`@araharah/routing`). Every miss class answers `200 null` — router-pending, never a wrong line.
5. **Guidance.** Accepting a route mints a guidance envelope (`POST /api/guidance`, 7200 s TTL); a scheduled cron (`*/2 * * * *`) projects progress along the frozen route snapshot and pushes due turn cards — a maneuver glyph photo with a live caption — into the chat, with a button back into the Mini App at `?g=`.
### HTTP surface
The Worker's `fetch` handler routes exactly six paths and returns `404` for anything else. All rejections carry a category only — never a payload, a user id, or a timestamp.
| Method | Path | Purpose |
|---|---|---|
| `POST` | `/telegram/webhook` | grammY webhook adapter. Fails closed with `500` if `WEBHOOK_SECRET` is missing, then constant-time-compares `X-Telegram-Bot-Api-Secret-Token` before any bot processing or KV touch. |
| `POST` | `/api/session` | The security gate. The client posts its verbatim `Telegram.WebApp.initData` string (capped at 4 KB, over-cap bodies are rejected `413` before parsing). An HMAC-validated, fresh identity receives a one-time opaque session token. |
| `GET` | `/api/location` | Polled by the Mini App with its in-memory `Bearer` token. The KV key derives from the resolved claim's `chat_id`, never from a client-supplied id, so one user's token can never read another user's pin. Returns honest nulls; a missing or expired token is `401`. |
| `POST` | `/api/location-fallback` | The "ask via chat" path when geolocation is denied. The bot sends a `request_location` reply keyboard into the user's own chat. Target chat id and locale come from the resolved claim — the request body is never read. A rejected Telegram send is a category-only `502`. |
| `POST` `GET` `DELETE` | `/api/guidance` | Guidance envelopes. `POST` mints a 7200 s session from a validated six-field route snapshot (a body `chat_id` is structurally ignored — identity is server-owned). `GET`/`DELETE` resolve the record and compare it to the claim, so a foreign and an absent session are indistinguishable `404`s. |
| `POST` | `/api/route` | Engine A's arm. Bearer-gated exactly like `/api/location`; returns a route summary, steps, and polyline6 geometry, or `200 null` on every miss class (honest degradation). Backed by the R2 road-graph bucket; a missing or corrupt graph degrades to router-pending, never a crash. |
```bash
# Mint a session from a Mini App initData string
curl -X POST http://localhost:8787/api/session --data-binary @initdata.txt
# → {"token":""}
# Poll the location relay with the token in memory
curl -H "Authorization: Bearer " http://localhost:8787/api/location
# → {"pin":null} (honest null, not a fabricated coordinate)
```
### Location acquisition in the Mini App
`web/src/location/chain.ts` is a three-link state machine with a locked order — **Telegram → WebView → chat pin** — and freshness is a separate axis from availability. A Telegram fix byte-identical to the last accepted one routes to the nudge, never to success; denial is a state, not an exception. The chain exposes a `Fix`-shaped abstraction with a pluggable cadence and hard-codes no interval, so continuous-mode polling is a later decision, not a rewrite. Past 45 seconds the strip flips to `SIGNAL LOST` and the last marker dims.
### Consuming the design tokens
`theme/src/tokens.css` is the single source of truth — 108 custom properties in all — 82 in the `@theme static` block, declared `static` so Tailwind v4's tree-shaking cannot drop tokens the MapLibre basemap derivation and plain-CSS consumers need, plus the 26 `--type-*` typography tokens in a separate `:root { }` block.
```css
/* raw token access — any stylesheet, no Tailwind required */
@import "@araharah/theme/dist/rams.css";
.instrument {
background: var(--color-signal-orange);
color: var(--color-matte-black);
padding: var(--spacing-space-md);
}
```
```ts
// build-time inlining of the Rams basemap style (never re-set at runtime)
import ramsStyle from "@araharah/theme/basemap/liberty-rams.json";
```
---
## Design system
The Telemetry Rams design system lives in `theme/` as a Tailwind v4 CSS-first token package — the single source of truth for every color, spacing, typography, and radius value in the project. Consume the tokens by importing `theme/src/tokens.css` (plain CSS custom properties, usable by any stylesheet or the MapLibre basemap) or the compiled stylesheet produced by `npm run build`. The token vocabulary mirrors the mockup screens verbatim, so markup derived from them maps one to one. Rams philosophy lives on in `DESIGN.md`, which is superseded for specifics — values are never restated outside the token package.
```bash
npm run build -w theme # src/theme.css → dist/rams.css (minified)
npm run sheet # build + print the sheet.html path
npm run gallery # build + screenshot → serve gallery.html and basemap on :8123
npm run audit # off-token audit of the rendered CSS — exits non-zero on violations
npm run capture # Playwright screenshots of the token sheet
```
The audit script treats "zero off-token values" as evidence rather than an eyeball claim: it scans rendered CSS and flags any color, spacing, typography, radius, shadow, or blur value that does not derive from `tokens.css`. Fonts (Geist, Space Grotesk) are self-hosted from `theme/fonts/` — both SIL Open Font License 1.1, no Google Fonts CDN.
---
## Commands
Run from the repo root, or with `-w `.
| Command | Description |
|---|---|
| `npm run build` | Build the theme, then the Mini App |
| `npm run dev` | Build, then run the Worker locally on port `8787` |
| `npm run deploy` | Build, then `wrangler deploy` + `set-webhook.mjs` |
| `npm run bot:test` / `npm run web:test` / `npm run search:test` / `npm run routing:test` | Run each package's zero-dependency test suite |
| `npm run bot:typecheck` / `npm run web:typecheck` / `npm run search:typecheck` / `npm run routing:typecheck` | `tsc --noEmit` |
| `npm run bot:commands` | Register the persistent Telegram command menu (EN + MS) |
| `npm run web:capture` | Capture Mini App screenshots |
| `npm run web:build:harness` | Dual build into `dist-harness/` with the mock installer and fetch stubs |
| `npm run privacy-audit` | Repo-wide privacy audit: storage gate, KV-TTL gate, category-only log gate, runtime-host allowlist, production-bundle telemetry scan (`--live` probes add KV expiry + cache headers) |
| `npm run budget-audit` | Free-tier budget audit: re-measures Worker CPU, bundle sizes, KV write classes, subrequests, and re-runs the golden corpora |
| `npm run search:corpus` | Search-quality gate: golden corpus against the shipped search module |
| `npm run routing:corpus` | Route-quality gate: fixture corpus (RT1–RT10) against the shipped routing module |
| `npm run routing:fixtures` | Refresh the committed route fixtures from the fixture HTTP source |
| `npm run sheet` / `gallery` / `audit` / `capture` | Design-token tooling (see above) |
The two build outputs must never share an `outDir` — the harness build emits mock fetch stubs that production must not carry.
---
## Privacy
Privacy is structural, not a policy page:
- Every write to the `chat_sessions` KV namespace carries an explicit `expirationTtl` on its call line; the storage test suite greps for this.
- Three TTL-only record families, nothing else: sessions — exactly four fields (user id, chat id, issued-at, language code) under a 900-second TTL; location pins — 300 seconds; guidance envelopes — 7200 seconds. Minting rotates any prior token for the chat.
- The turn-card cron is **stateless**: it reads KV, sends cards, and writes nothing.
- The Mini App holds its session token in a module-scope closure. There is no `localStorage`, `sessionStorage`, cookie, IndexedDB, or Cache API anywhere in `web/src` — the `no-storage` test suite pins this.
- Nothing durable, nothing reconstructable. A token cannot outlive the 15-minute initData freshness proof that minted it.
- Two audits back all of this with evidence: `npm run privacy-audit` (storage, TTL, category-only logs, runtime-host allowlist, shipped-bundle telemetry scan) and `npm run budget-audit` (the free-tier ceilings, measured — see `docs/BUDGETS.md`). v1 carries **zero telemetry**; there is nothing to opt into yet.
## Repository layout
```
theme/ @araharah/theme — tokens.css, components.css, theme.css, fonts/, basemap/, scripts/
bot/ @araharah/bot — src/webhook.ts entry, bot/, kv/, security/, routing/, guidance/, i18n/, scripts/, wrangler.jsonc
web/ @araharah/web — src/main.ts entry, location/, route/, guidance/, search/, map/, session/, telegram/, ui/, mock/
search/ @araharah/search — src/types.ts, normalize.ts, distance.ts, score.ts, gazetteer.ts, source.ts, data/kl-gazetteer.json
routing/ @araharah/routing — src/graph.ts, snap.ts, astar.ts, polyline.ts, geo.ts, fixture-source.ts, http-source.ts, data/kl-roadgraph.v1.bin
stitch_minimalist_route_navigator/ read-only mockup screens (class-vocabulary source for the theme build)
DESIGN.md Rams philosophy — superseded for any specific value
```
## License
Code is licensed under **GPL-3.0** — the full text is in [LICENSE](./LICENSE). The curated KL
gazetteer (`search/src/data/kl-gazetteer.json`) is **data**, licensed separately under the Open
Database License (ODbL) v1.0 with attribution to © OpenStreetMap contributors; the dual-licence
note and the share-alike scope are in [LICENSES.md](./LICENSES.md).