Core Concepts
The seven ideas that explain everything arah² does. Read this before any other doc — the rest of docs/ assumes these.
1. The privacy law: nothing persists
arah² stores nothing that identifies you beyond what you explicitly send it. The concrete rules, enforced by tooling rather than promises:
| Surface | Law | Enforcement |
|---|---|---|
| KV storage | TTL-only — every write carries an expiry; three families: sessions 900s · location pins 300s · guidance envelopes 7200s | kv-ttl gate + live --live probe (lists keys, asserts expiry) |
| Coordinates | Live in the Mini App's memory only; a route snapshot lives only inside its 7200s TTL envelope, gone at expiry or trip end | storage-api gate (repo-wide grep) + the no-storage test suites |
| Logs | Category-only — log lines name a surface and a rejection class, never coordinates, ids, tokens, or payload | log-vocabulary gate (schema-scans every console.log) |
| Telemetry | Zero — no analytics, no beacons, nothing to opt into; the only runtime fetches are OpenFreeMap tiles, the Telegram API, and the app's own endpoints | bundle-telemetry + runtime-hosts gates (printed host inventories) |
The identity floor: you authenticate with Telegram's own initData — HMAC-validated server-side against the bot token, 900-second freshness, exchanged once for an opaque random session token held in the Mini App's memory. No profile is ever built.
2. Backend ladders: interfaces, not products
Every "engine" is an interface with a documented escalation ladder — so no capability ever wedges to a single implementation:
SearchSource— gazetteer #1 (curated KL, in-Worker) → WASM geocoder #2 (OSS track) → Photon #3 (documented).RoutingSource— fixtures #1 (golden KL pairs) → engine A #2 (live: CSR road graph in R2, typed-array A* in the Worker) → fully client-side router #3 (the static-hosted endgame) → Valhalla #4 (documented).
Each rung answers the same contract; failures resolve honestly (null → a designed "router pending" surface — never a blank map, never a fake route).
3. The $0 law
Every service is on a free tier, enforced by measurement: npm run budget-audit compares real numbers (Worker CPU, KV ops/day, bundle bytes, subrequests) against the free ceilings, and prints violations honestly. The known negotiated class: short KL reroutes run 2–8ms in-budget; cross-metro routes degrade to the router-pending state until the ALT-landmarks rung lands. The cron is tuned inside the KV list-op ceiling (2-minute ticks ⇒ 720/day < 1,000).
4. The bot is the transport; the Mini App is the product
Search happens in chat (/cari KLCC → a native venue card with alternates). Choosing opens the Mini App preloaded (?dest=<id> / start_param — the two carriers). Inside: location chain (Telegram LocationManager → WebView geolocation → chat-pin fallback), Rams-styled map, route, then turn-by-turn guidance. When minimized, the cron pushes schematic turn-cards to chat (glyph + street + ETA — best-effort projection, zero KV writes per tick). Re-opening resumes at the progressed position.
5. Honest failure as the design language
Every dead end is a designed surface: denied location (with a settings deep-link), signal lost, router pending, destination unavailable, abandon-route confirm, "trip ended, data deleted". No blank screens — the FM1–FM7 matrix pins all seven failure classes with captures.
6. Design system binding
theme/ is the single source of truth (Telemetry Rams: zero radius, 8px grid, Space Grotesk/Geist, the 60/30/10 color law where signal-orange is the route accent). The Mini App consumes tokens as a build-time dependency; the map stays Rams-constant while the shell re-slots to Telegram's light/dark theme. npm run audit greps for invented values.
7. Forkability is the license
GPL-3.0 (code) + ODbL (data). One command deploys to your Cloudflare with your bot; the audit tools are yours too — run npm run privacy-audit before your first driver. Secrets live only in gitignored .dev.vars; no hard-coded identity anywhere.
Concepts verified against the live codebase (2025-10-25); see docs/ARCHITECTURE.md for the module map and docs/API.md for the endpoint laws.
arah²
Packages
Repo
- Source tree
- API — API
- Deployment — Deployment
- Contributing — Contributing
- Core concepts — Core-Concepts