# 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=` / `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.*