66 lines
4.4 KiB
Markdown
66 lines
4.4 KiB
Markdown
<!-- generated-by: gsd-doc-writer -->
|
||
|
||
# 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.*
|