docs: README logo 560px + quickstart/future sections; new CORE-CONCEPTS doc; wiki synced
This commit is contained in:
araharah-executor
+1
-1
Submodule .planning/tmp/arah2.wiki updated: 848a140b32...d8011e3d73
@@ -1,7 +1,7 @@
|
||||
<!-- generated-by: gsd-doc-writer -->
|
||||
|
||||
<p align="center">
|
||||
<img src="assets/MASTER_FILE-arah2_logo.svg" alt="arah² logo" width="280">
|
||||
<img src="assets/MASTER_FILE-arah2_logo.svg" alt="arah² logo" width="560">
|
||||
</p>
|
||||
|
||||
# arah²
|
||||
@@ -109,6 +109,84 @@ cp bot/.dev.vars.example bot/.dev.vars
|
||||
|
||||
---
|
||||
|
||||
## 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 <your fork>
|
||||
cd arah2 && npm install
|
||||
cp bot/.dev.vars.example bot/.dev.vars
|
||||
```
|
||||
|
||||
**3. Fill `bot/.dev.vars`** (gitignored — never commit):
|
||||
|
||||
```
|
||||
BOT_TOKEN=<token from step 1>
|
||||
WEBHOOK_SECRET=<any long random string — you choose it>
|
||||
WEBHOOK_URL=https://<your-worker>.workers.dev
|
||||
MINI_APP_URL=https://<your-worker>.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
|
||||
|
||||
@@ -0,0 +1,65 @@
|
||||
<!-- 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.*
|
||||
Reference in New Issue
Block a user