Arah2/docs/ARCHITECTURE.md

<!-- generated-by: gsd-doc-writer -->
# arah² — Architecture

## System Overview

arah² is a Telegram-first GPS navigator: a grammY bot (`arah2bot`) running as a single
Cloudflare Worker serves both the Telegram webhook **and** the static Mini App bundle
served from the same origin. The Mini App (`@araharah/web`, a Vite + MapLibre GL
application) authenticates with the Worker by posting its verbatim
`Telegram.WebApp.initData` to `POST /api/session`, receives a short-lived opaque bearer
token, and then acquires a position through a three-link chain (Telegram
`LocationManager` → WebView `navigator.geolocation` → chat-relayed pin). All server state
lives in a TTL-only Cloudflare KV namespace, so the system has no database, no persistent
storage, and no analytics. `@araharah/theme` is the shared design-token package: it
compiles Tailwind v4 CSS consumed by the web app and is the derivation source for the
Rams basemap style the map renders.

Architecturally this is a **three-workspace npm monorepo in a layered/hexagonal
arrangement**: a stateless edge worker with a KV-backed repository layer, a
framework-free TypeScript client with its own repository + adapter layers, and a pure
build-time token/cartography package that both consume.

```mermaid
graph TD
    classDef client fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A
    classDef worker fill:#D9D2C6,stroke:#736B1E,stroke-width:2px,color:#1A1A1A
    classDef store fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF
    classDef build fill:#1A1A1A,stroke:#000000,stroke-width:2px,color:#FFF8F0

    A["Telegram client<br/>chat + Mini App webview"]:::client
    B["@araharah/bot Worker<br/>src/webhook.ts"]:::worker
    C["grammY handlers<br/>commands + location-fallback"]:::worker
    D["Security<br/>initdata.ts HMAC"]:::worker
    E["KV chat_sessions<br/>TTL-only"]:::store
    F["@araharah/web Mini App<br/>src/main.ts"]:::client
    G["Session client + store<br/>src/session/"]:::client
    H["Location chain<br/>src/location/"]:::client
    I["MapLibre map + UI<br/>src/map/, src/ui/"]:::client
    J["@araharah/theme<br/>dist/rams.css + basemap"]:::build

    A -->|"POST /telegram/webhook"| B
    A -->|"loads Mini App"| B
    B --> C
    B --> D
    B --> E
    C --> E
    C -->|"sendMessage reply keyboard"| A
    F -->|"POST /api/session initData"| B
    F -->|"GET /api/location Bearer"| B
    F -->|"POST /api/location-fallback"| B
    G --> F
    H --> G
    F --> H
    H --> I
    J -->|"compiled CSS + inlined style JSON"| F
```

## Component Diagram

```mermaid
graph LR
    classDef ws fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A
    classDef wsfill fill:#FFF8F0,stroke:#EB8008,stroke-width:2px,color:#1A1A1A
    classDef botfill fill:#F5EDE0,stroke:#736B1E,stroke-width:2px,color:#1A1A1A
    classDef store fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF
    classDef ext fill:#E0D9CD,stroke:#564335,stroke-width:2px,color:#1A1A1A

    subgraph ROOT["root — npm workspaces"]
        direction TB
        subgraph THEME["theme · @araharah/theme"]
            direction TB
            T1["src/tokens.css<br/>@theme static, 55 colors"]:::wsfill
            T2["src/components.css"]:::wsfill
            T3["basemap/build.mjs"]:::wsfill
            T4["dist/rams.css"]:::wsfill
            T5["basemap/liberty-rams.json"]:::wsfill
            T1 --> T4
            T2 --> T4
            T1 -->|"derives roles"| T3
            T3 --> T5
        end
        subgraph WEB["web · @araharah/web"]
            direction TB
            W1["src/main.ts"]:::wsfill
            W2["src/session/"]:::wsfill
            W3["src/location/"]:::wsfill
            W4["src/map/"]:::wsfill
            W5["src/ui/ + src/telegram/"]:::wsfill
            W6["src/shell.css"]:::wsfill
            W7["dist/ (served)"]:::wsfill
            W1 --> W2
            W1 --> W3
            W1 --> W4
            W1 --> W5
            W1 --> W7
            W4 --> W7
            W5 --> W7
        end
        subgraph BOT["bot · @araharah/bot"]
            direction TB
            B1["src/webhook.ts"]:::botfill
            B2["src/security/initdata.ts"]:::botfill
            B3["src/bot/"]:::botfill
            B4["src/kv/"]:::botfill
            B5["src/config.ts Env"]:::botfill
            B1 --> B2
            B1 --> B3
            B1 --> B4
            B1 --> B5
        end
        KV[("KV namespace chat_sessions<br/>session:* 900s · chat:* · loc:* 300s")]:::store
        TG["Telegram Bot API"]:::ext
        OFM["OpenFreeMap tiles"]:::ext
    end

    WEB -->|"workspace dep @araharah/theme"| THEME
    BOT -->|"assets binding ../web/dist"| WEB
    B1 --> KV
    B4 --> KV
    B3 <-->|"webhookCallback / sendMessage"| TG
    W3 <-->|"chat pin"| TG
    W4 --> OFM
```

## Workspaces Dependency Graph

```mermaid
graph TD
    classDef pkg fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A
    classDef dep fill:#736B1E,stroke:#4A440F,stroke-width:2px,color:#FFF8F0
    classDef out fill:#D9D2C6,stroke:#736B1E,stroke-width:2px,color:#1A1A1A

    ROOT["araharah (private root)"]:::out
    TH["@araharah/theme"]:::pkg
    BT["@araharah/bot"]:::pkg
    WB["@araharah/web"]:::pkg
    KVS[("KV chat_sessions")]:::dep
    TGAPI["Telegram Bot API"]:::dep

    ROOT -->|"workspaces"| TH
    ROOT -->|"workspaces"| BT
    ROOT -->|"workspaces"| WB
    WB -->|"dependencies: @araharah/theme *"| TH
    BT -->|"static assets ../web/dist"| WB
    BT --> KVS
    BT --> TGAPI
    WB -->|"api routes"| BT
```

`@araharah/web` declares `"@araharah/theme": "*"` — the only workspace-to-workspace
runtime import in the repo (`@araharah/theme/dist/rams.css` in `web/src/shell.css`,
`@araharah/theme/basemap/liberty-rams.json` in `web/src/map/map.ts`). The bot has no
workspace dependency; its coupling to web is a **build-order coupling only** — the
root `build` script builds theme then web, and the Worker's `[assets]` binding points
at `../web/dist`.

## Data Flow

### 1. Telegram command surface (bot → chat)

Telegram delivers an update to `POST /telegram/webhook`. The Worker first fails closed
if `WEBHOOK_SECRET` is unset, then hands the request to grammY's
`webhookCallback(bot, "cloudflare-mod", …)`, which constant-time-compares the
`X-Telegram-Bot-Api-Secret-Token` header. `createBot(env)` is instantiated **per
request** (the token only arrives with `env`), registers the command stack, and grammY
dispatches:

```
POST /telegram/webhook → webhookCallback (secret check) → createBot(env)
  → registerStart / registerHelp / registerPrivacy → pickLocale(language_code)
  → ctx.reply(plain text, link_previews disabled)
```

All user-facing copy comes from `bot/src/i18n/strings.ts`; `bot/scripts/register-commands.mjs`
derives the persistent `/setMyCommands` menu descriptions from the same `helpMenu` lines,
so menu and reply cannot drift.

### 2. Mini App boot (session handshake)

```mermaid
sequenceDiagram
    participant WA as WebApp webview
    participant MAIN as web/src/main.ts
    participant SESS as session/client.ts
    participant WK as Worker /api/session
    participant ID as security/initdata.ts
    participant KV as KV chat_sessions

    MAIN->>MAIN: applySafeArea(resolveSafeInsets(wa))
    MAIN->>MAIN: bootMap() mounts MapLibre FIRST
    MAIN->>MAIN: register strip, cards, recenter
    MAIN->>SESS: createSession(wa.initData) [verbatim string]
    SESS->>WK: POST /api/session, body = initData (≤ 4 KB)
    WK->>ID: validateInitData(raw, BOT_TOKEN)
    ID-->>WK: ok | malformed | tampered | stale
    WK->>KV: mintSession(chat_sessions, claim)
    KV-->>WK: opaque UUID token
    WK-->>SESS: 200 { token }
    SESS->>SESS: setSession(token) [module scope only]
```

The HMAC path: `dataCheckString` = all initData fields **minus `hash` only**, sorted by
field name, joined with `\n`; secret key = `HMAC-SHA256(key="WebAppData",
message=botToken)`; check = `HMAC-SHA256(key=secretKey, message=dataCheckString)`
compared in constant time against `hash`. `signature` participates in the check.
`auth_date` older than 900 s is rejected as `stale`.

### 3. Location acquisition chain

```mermaid
flowchart TD
    classDef s fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A
    classDef ok fill:#F5EDE0,stroke:#736B1E,stroke-width:2px,color:#1A1A1A
    classDef no fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF

    START["acquireFix(deps, lastAccepted)"]:::ok
    L1{"telegramLocationSupported<br/>isVersionAtLeast 8.0"}:::ok
    NUDGE{"looksStale(prev, fix)<br/>haversine < 0.01 m"}:::ok
    L2{"webviewLocationSupported"}:::ok
    L3{"getToken() !== null"}:::ok
    LIVE["return { fix, state: live }"]:::s
    DEN1["denied / timeout"]:::no
    DEN2["denied / no-permission"]:::no

    START --> L1
    L1 -->|"yes"| NUDGE
    NUDGE -->|"no"| LIVE
    NUDGE -->|"yes"||"discarded webview read"| L1
    L1 -->|"no"| L2
    L2 -->|"yes + fix"| LIVE
    L2 -->|"no fix"| L3
    L3 -->|"yes: bounded 60s poll"| LIVE
    L3 -->|"poll expired"| DEN1
    L3 -->|"no token"| DEN2
```

Link 1 (`telegram.ts`) calls `LocationManager.init()` then `getLocation()`, with a hard
8 s wrapper timeout because the API documents no timeout. A byte-identical fix to the
last accepted one routes to the nudge: one **discarded** webview read refreshes the
Android native cache, then telegram is retried. Link 2 (`webview.ts`) calls
`navigator.geolocation.getCurrentPosition` with `maximumAge: 0`. Link 3
(`chat-pin.ts`) polls `GET /api/location` every 2 s for at most 60 s.

### 4. Chat-pin relay (the Desktop-Telegram path)

```mermaid
sequenceDiagram
    participant U as User (chat)
    participant B as Bot handler
    participant KV as KV loc:chat_id
    participant MA as Mini App
    participant W as Worker

    MA->>W: POST /api/location-fallback (Bearer token)
    W->>W: getClaimByToken → claim.chat_id
    W->>B: requestLocationFallback(bot, chat_id, locale)
    B->>U: reply keyboard, request_location: true
    U->>B: taps button, native location picker
    B->>KV: writePin(kv, chat_id, { lat, lng, acc })  expirationTtl 300
    loop every 2 s, bounded 60 s
        MA->>W: GET /api/location (Bearer token)
        W->>KV: getPin(chat_sessions, claim.chat_id)
        KV-->>W: LocationPin | null
        W-->>MA: { pin }  (200) or { pin: null }
    end
```

Both `/api/location` and `/api/location-fallback` derive the target `chat_id` from the
**resolved session claim**, never from client input, and derive locale from
`claim.language_code`. Telegram has no push channel from chat to webview, so this poll
is server-mediated by necessity.

### 5. Worker routing table

| Method | Path | Handler in `bot/src/webhook.ts` | Purpose |
| --- | --- | --- | --- |
| POST | `/telegram/webhook` | inline in `fetch()` | grammY webhook adapter + secret-token compare |
| POST | `/api/session` | `handleSession` | initData → one-time opaque session token |
| GET | `/api/location` | `handleLocation` | Bearer-authenticated chat-pin relay |
| POST | `/api/location-fallback` | `handleLocationFallback` | Ask the bot to send the reply keyboard |
| * | anything else | — | 404 |

`run_worker_first: ["/api/*", "/telegram/*"]` guarantees the Worker's `fetch` owns these
paths before the static asset fallback runs; every other path resolves to the `web/dist`
bundle.

## Build & Deploy Topology

```mermaid
graph LR
    classDef step fill:#1A1A1A,stroke:#000000,stroke-width:2px,color:#FFF8F0
    classDef art fill:#D9D2C6,stroke:#736B1E,stroke-width:2px,color:#1A1A1A
    classDef cloud fill:#EB8008,stroke:#8A4C00,stroke-width:2px,color:#1A1A1A
    classDef store fill:#ED3F1C,stroke:#8C1F0A,stroke-width:2px,color:#FFFFFF

    T1["theme: tailwindcss -i src/theme.css -o dist/rams.css --minify"]:::step
    T2["theme: basemap/build.mjs<br/>fetch liberty → derive roles → liberty-rams.json"]:::step
    W1["web: vite build → dist/"]:::step
    W2["web: vite build --mode harness → dist-harness/"]:::step
    B1["bot: wrangler deploy"]:::step
    B2["bot: scripts/set-webhook.mjs"]:::step
    AR1["theme/dist/rams.css + fonts"]:::art
    AR2["web/dist (index.html, hashed assets,<br/>inlined liberty-rams style)"]:::art
    AR3["web/dist-harness (never deployed)"]:::art
    EDGE["Cloudflare Worker araharah-bot<br/>[assets] ../web/dist"]:::cloud
    KVS[("KV chat_sessions")]:::store

    T1 --> W1
    T2 --> W1
    T1 --> AR1
    W1 --> AR2
    W2 --> AR3
    AR2 --> EDGE
    B1 --> EDGE
    B1 --> B2
    EDGE --> KVS
```

The root scripts encode the ordering: `npm run build` = `build -w theme && build -w web`;
`npm run deploy` = `npm run build && npm run deploy -w bot` (which is
`wrangler deploy && node scripts/set-webhook.mjs`). `bot/wrangler.jsonc` binds
`assets.directory` to `../web/dist`, so `web/dist` must exist before a bot deploy.

The two web builds never share an outDir: `vite.config.ts` sets
`outDir: "dist-harness"` only under `--mode harness` and defines
`__ARAHARAH_HARNESS__` to `true` there and `false` everywhere else, so the mock
installer and the `fetch` stubs in `web/index.html` are dead-code-eliminated from
production. `web/test/build-artifact.test.mjs` (BA1–BA6) proves the shipped bundle
references no third-party CDN, self-hosts the woff2 fonts, contains the inlined Rams
style, and carries neither `installMockWebApp` nor `__ARAHARAH_MOCK__`.

<!-- VERIFY: production Worker hostname and KV namespace id come from bot/wrangler.jsonc and bot/.dev.vars, both environment-specific. -->

## Key Abstractions

### `@araharah/bot`

| Abstraction | File | Description |
| --- | --- | --- |
| `Env` | `bot/src/config.ts` | Typed contract: `BOT_TOKEN`, `WEBHOOK_SECRET` (must be non-empty — the webhook fails closed without it), `chat_sessions: KVNamespace`. |
| `default { fetch }` | `bot/src/webhook.ts` | The `ExportedHandler<Env>` — four routes, 404 otherwise. Bot is constructed per request. |
| `validateInitData(raw, botToken, opts)` | `bot/src/security/initdata.ts` | Pure HMAC-SHA256 validation of Telegram WebApp initData. Depends only on `crypto.subtle`, so it runs unchanged in Workers and bare Node. Returns `InitDataResult`. |
| `SessionClaim` / `mintSession` / `getClaimByToken` / `getTokenForChat` | `bot/src/kv/sessions.ts` | TTL-only session layer. `SESSION_TTL_SECONDS = 900`. Key scheme `session:<token>` → claim, `chat:<chat_id>` → current token. Rotate-on-new with a best-effort reconciliation sweep. |
| `LocationPin` / `writePin` / `getPin` / `clearPin` | `bot/src/kv/location-pin.ts` | TTL-only pin layer. `PIN_TTL_SECONDS = 300`. Key `loc:<chat_id>`. `getPin` range-validates on read. |
| `createBot(env, opts)` | `bot/src/bot/bot.ts` | grammY factory; wires `/start` + `/mula`, `/help`, `/privacy` + `/privasi`, and the location-fallback message handler. |
| `requestLocationFallback(bot, chatId, locale)` | `bot/src/bot/handlers/location-fallback.ts` | Sends the `request_location` reply keyboard. Single caller: `handleLocationFallback`. |
| `strings` / `pickLocale` | `bot/src/i18n/strings.ts` | The bot's entire copy surface (`en`, `ms`). `pickLocale` maps an `ms`/`ms-*` language code to Malay, everything else to English. |
| `KvLike` | `bot/src/kv/*.ts` | Structural KV interface — lets tests pass a fake without depending on Workers types. |

### `@araharah/web`

| Abstraction | File | Description |
| --- | --- | --- |
| `Fix` | `web/src/location/types.ts` | The single normalized position shape every source reduces to: `lat`, `lng`, `accuracyM`, `headingDeg`, `ts`, `source`. Freshness lives in the fix. |
| `LocationState` | `web/src/location/types.ts` | Discriminated union: `idle` / `validating` / `acquiring` / `awaiting-pin` / `live` / `stale` / `denied`. |
| `acquireFix(deps, lastAccepted)` | `web/src/location/chain.ts` | The three-link state machine. Pluggable cadence — no `setInterval`, no `watchPosition`. |
| `isFixStale(fix, nowMs)` / `fixAgeSeconds` | `web/src/location/chain.ts` | The 45 s signal-lost threshold and the `FIX Ns AGO` telemetry helper. |
| `TelegramWebAppLike` | `web/src/telegram/webapp.ts` | Hand-rolled ~12-member contract for `window.Telegram.WebApp`. `getWebApp()` may honestly return `null` off-Telegram. |
| `createSession(initData)` | `web/src/session/client.ts` | POSTs the verbatim initData string; returns `{ ok: true, token }` or a `malformed`/`tampered`/`stale`/`network` reason. |
| `setSession` / `getSession` / `isSessionStale` / `clearSession` | `web/src/session/store.ts` | Module-scope token holder. No persistence call anywhere in the file. |
| `bootMap(container)` | `web/src/map/map.ts` | MapLibre v6 bootstrap with the build-time-inlined Rams style. Returns `null` on `GPUInitializationError`. |
| `createPositionMarker()` | `web/src/map/marker.ts` | SVG accuracy circle + 20 px dot + heading cone. Cone hidden entirely when heading is `null`. |
| `createFollowController(map, onModeChange)` | `web/src/map/follow.ts` | following/free camera. Only a user gesture (`movestart` with `originalEvent`) flips to free. |
| `createStatusStrip(host)` | `web/src/ui/strip.ts` | The status band — state lamp + state word on the left, telemetry on the right. |
| `buildBootCard` / `buildDeniedCard` / `buildSignalLostCard` | `web/src/ui/cards.ts` | Rams card surfaces composed from theme component classes; zero inline copy. |
| `createRecenterControl(host, locale, onRecenter)` | `web/src/ui/recenter.ts` | 40×40 follow plate with three instant notch states. |
| `watchTheme(wa)` / `resolveBranch` | `web/src/telegram/theme.ts` | Telegram light/dark signal → `data-tg-theme` slot switch. MapLibre is deliberately absent. |
| `resolveSafeInsets` / `applySafeArea` | `web/src/telegram/safe-area.ts` | Union of CSS `env()` and `WebApp.safeAreaInset`, max per edge, emitted as CSS custom properties. |
| `wireBackButton(wa, hasOverlay)` | `web/src/telegram/backbutton.ts` | Total function — at the root state a click closes the app; no no-op handler. |
| `installMockWebApp(options)` | `web/src/mock/telegram-mock.ts` | Harness-only fake `window.Telegram.WebApp` with a dev-signed initData. Excluded from `web/dist`. |
| `localeFromInitData(raw)` | `web/src/i18n/strings.ts` | Parses the locale out of the raw initData string — the session response carries only `{ token }`. |

### `@araharah/theme`

| Abstraction | File | Description |
| --- | --- | --- |
| `@theme static` block | `theme/src/tokens.css` | 55 `--color-*` tokens plus spacing and typography. `static` forces every token into the compiled CSS so the package is consumable as plain custom properties. |
| `theme/src/theme.css` | `theme/src/theme.css` | Entry stylesheet — `@import`s tailwindcss, tokens, components; declares eight self-hosted `@font-face` rules; defines the `--shell-bg` / `--shell-on-surface` theme slots. |
| Component classes | `theme/src/components.css` | `.card`, `.btn-primary`, `.btn-secondary`, `.chip-*`, `.maneuver-*`, `.text-*`, `.toggle*`, `.input-field`, `.checkbox`. |
| `build.mjs` | `theme/basemap/build.mjs` | Forks OpenFreeMap `liberty`, deriving every cartographic color from `tokens.css` via `desaturate(tokenHex, satMultiplier, lightnessPerRole)` with saturation clamped to `[0.06, 0.12]`. |
| `liberty-rams.json` | `theme/basemap/liberty-rams.json` | The generated style. Accent guard fails the build if `#EB8008` / `#ED3F1C` / `#736B1E` leak into any layer. `building-3d` is removed (faux 3D). |

## Directory Structure Rationale

```
araharah/
├── package.json          # private root; workspaces + build ordering only
├── bot/                  # @araharah/bot — the Cloudflare Worker
│   ├── src/
│   │   ├── webhook.ts        # the single fetch handler; four routes
│   │   ├── config.ts         # Env contract
│   │   ├── bot/              # grammY factory, commands/, handlers/
│   │   ├── security/         # initdata.ts — pure, isolation-free crypto
│   │   ├── kv/               # sessions.ts, location-pin.ts — TTL-only repos
│   │   └── i18n/strings.ts   # every user-facing bot string
│   ├── scripts/              # set-webhook, register-commands, set-menu-button
│   ├── test/                 # hand-rolled zero-dependency runner + suites
│   └── wrangler.jsonc        # worker name, assets binding, run_worker_first, KV
├── web/                  # @araharah/web — the Mini App
│   ├── src/
│   │   ├── main.ts           # boot choreography (order is load-bearing)
│   │   ├── session/          # client.ts (network), store.ts (memory)
│   │   ├── location/         # chain.ts + telegram/webview/chat-pin sources
│   │   ├── telegram/         # webapp, theme, backbutton, safe-area
│   │   ├── map/              # map.ts, marker.ts, follow.ts
│   │   ├── ui/               # strip.ts, cards.ts, recenter.ts
│   │   ├── mock/             # harness-only Telegram fake
│   │   ├── i18n/strings.ts   # every user-facing shell string
│   │   └── shell.css         # Rams chrome; imports @araharah/theme/dist/rams.css
│   ├── test/                 # runner + gate suites (copy, storage, artifact, chain)
│   ├── scripts/capture.mjs   # screenshot capture
│   └── vite.config.ts        # dual-build dist/ vs dist-harness/
├── theme/                # @araharah/theme — design tokens + cartography
│   ├── src/                   # tokens.css, components.css, theme.css, sheet.html
│   ├── fonts/                 # self-hosted Geist + Space Grotesk woff2
│   ├── basemap/               # build.mjs + generated liberty-rams.json
│   ├── scripts/               # audit.mjs (token audit), screenshot.mjs
│   └── dist/rams.css          # compiled output
├── stitch_minimalist_route_navigator/   # read-only design reference (mockups)
└── docs/
```

Rationale for the boundaries:

- **`bot/src/webhook.ts` owns routing; nothing else dispatches.** The Worker is the only
  place that decides which path runs, so `run_worker_first` and the secret-token gate
  apply uniformly.
- **`bot/src/security/` and `bot/src/kv/` are dependency-light on purpose.**
  `initdata.ts` imports nothing from grammY and runs in both Workers and bare Node;
  `kv/*.ts` take a structural `KvLike` so the suites pass fakes.
- **`bot/src/i18n/strings.ts` is the single copy source.** The commands register
  script derives its menu text from the same `helpMenu` lines, and `bot/test/commands.test.mjs`
  gates that the `/privacy` copy still matches the `SessionClaim` fields in
  `sessions.ts`.
- **`web/src/location/` separates sources from the chain.** Each source is a small module
  that normalizes to `Fix` and answers `null` for denial; `chain.ts` owns ordering and
  knows nothing about any single source's API.
- **`web/src/session/` splits network from state.** `client.ts` owns fetch and error
  vocabulary; `store.ts` owns the in-memory token and the 900 s staleness rule. Neither
  ever touches storage.
- **`web/src/telegram/` is the only place that touches `Telegram.WebApp`.** Every other
  module takes the narrow `TelegramWebAppLike` interface, which is what lets the mock,
  the test fakes, and real clients satisfy the same contract.
- **`theme/` is pure build-time.** It exports no runtime code — a CSS bundle and a JSON
  style. That is why `web` can depend on it without pulling a bundler into the token
  package.
- **`stitch_minimalist_route_navigator/` is `@source`-scanned, never edited.** The theme
  compiles every class the four mockups use so the design vocabulary stays provable
  against the shipped CSS.

## Cross-Cutting Concerns

### Privacy by construction

Two grep gates pin this rather than documenting it:

- `bot/test/privacy.test.mjs` — every `put` on `chat_sessions` must carry an explicit
  `expirationTtl` on the same call line. No write path can persist without a TTL.
- `web/test/no-storage.test.mjs` — comments stripped, every `web/src` file scanned; zero
  occurrences of `localStorage`, `sessionStorage`, `indexedDB`, `caches`,
  `document.cookie`, `WebApp.DeviceStorage`, `WebApp.SecureStorage`, `WebApp.CloudStorage`.

The persisted surface is exactly `SessionClaim` (user_id, chat_id, issued_at,
language_code) for 900 s and `LocationPin` (latitude, longitude, horizontal_accuracy)
for 300 s. The client holds the token and the last fix in module scope only.

### Access control

The `chat_id` used by `/api/location` and `/api/location-fallback` is always resolved
from the session claim, and the locale from `claim.language_code`. The request body of
the fallback route is never read — no chat id or language can arrive from the client.

### Honest degradation

Every degradation is a labeled state, never a silent one or a fabricated value:
`bootMap()` returning `null` renders the shell over `--color-surface-dim` with
`data-map="absent"`; a null heading hides the marker cone rather than guessing an
orientation; `getPin` range-validates so a corrupt record cannot fly the camera to null
island; the poll is bounded at 60 s so `AWAITING PIN` cannot persist; every source
timeout resolves `null` so the chain always advances.

### Logging

The Worker's only log statements are category-only — `malformed`, `tampered`, `stale`,
`unauthorized`, `misconfigured`, `telegram-send`. Never raw payloads, never user ids,
never timestamps. Rejection responses carry the category only.

### Testing

Both `bot/test` and `web/test` use the same hand-rolled zero-dependency runner
(`runner.mjs` + `harness.mjs`), auto-discovering `*.test.mjs`. `theme` runs
`scripts/audit.test.mjs` in the same shape. Gates are grep/introspection assertions
against source and build artifacts, not just behavioral assertions.

## What Is Not Built Yet

The following appear in `IDEAS.md` as roadmap items and are **not** in the codebase:
routing engines (Valhalla/OSRM), Neon/Postgres, RabbitMQ, Prometheus/Grafana, Resend,
Cloudflare R2, Photon geocoding. The current system is exactly the two implemented
phases: the bot skeleton with initData-gated sessions and TTL-only KV, and the Mini App
shell with the three-link location chain and the Rams basemap. Routing/guidance is
Phase 5+.