# Requirements: araharah

**Defined:** 2026-10-22
**Core Value:** A user finds a local destination via Telegram and gets there with reliable turn-by-turn guidance — tracked by nothing beyond what they explicitly opted in to.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Onboarding & Entry

- [x] **ONBD-01**: User can open the araharah bot and start with /start — a concise explanation plus a always-available command menu (/help, /privacy)
- [ ] **ONBD-02**: User can open the Mini App from a search result with their destination preloaded (no re-entry in the webview)
- [ ] **ONBD-03**: User can add araharah to their phone home screen and launch search/navigation from there (addToHomeScreen + startapp deep-link)

### Destination Search

- [ ] **SRCH-01**: User can type a destination query (e.g. "KLCC") and receive a shortlist containing the right KL-metro landmark/POI
- [ ] **SRCH-02**: User gets useful results despite abbreviations and typos (Jln↔Jalan, Tmn↔Taman, missing spaces, common Malay address shorthand)
- [ ] **SRCH-03**: For a chosen destination, a native venue card is sent in chat, confirming where we're going before navigation opens

### Current Location

- [x] **GEO-01**: The Mini App can obtain the user's current location via Telegram LocationManager, with permission persisting across sessions
- [x] **GEO-02**: When in-app location fails (denied permissions or Desktop Telegram without geolocation), the chat "send location" keyboard fallback obtains the origin
- [x] **GEO-03**: The user's location is never written to persistent storage — only ephemeral TTL server state exists during the active trip

### Routing & Route Choice

- [ ] **RTNG-01**: User sees a calculated route from current location to destination drawn on a Rams-styled map (grayscale grounding, accent route)
- [ ] **RTNG-02**: User can choose among up to 3 alternative routes presented as quiet Rams cards (time, distance, one-line difference)

### Turn-by-Turn Guidance

- [ ] **GUID-01**: While driving, the user sees a prominent next-maneuver banner (distance + arrow + street name) and a collapsible full maneuver list
- [ ] **GUID-02**: After a missed turn, the app detects it and auto-recalculates from the current position without asking or blaming
- [ ] **GUID-03**: The user sees ETA and remaining distance progress with each location fix (honest, self-paced ETA — no fake traffic confidence)
- [ ] **GUID-04**: Guidance surfaces haptic cues at maneuver points (eyes-free, voice-free v1)
- [ ] **GUID-05**: When the user minimizes the app mid-drive, the bot pushes chat turn-cards (map snapshot + next maneuver + ETA) for the remainder of the trip — best-effort projections
- [ ] **GUID-06**: Re-opening the Mini App mid-trip resumes live guidance seamlessly at the user's progressed position

### Platform Hygiene (Mini App)

- [ ] **PX-01**: The Telegram BackButton walks app states (search → routes → guidance → back to search) and never dead-ends
- [x] **PX-02**: The app follows Telegram light/dark themes for chrome while the map keeps the Rams cartography constant
- [ ] **PX-03**: During guidance, safe areas are respected, vertical-swipe-close is disabled, and closing shows the "abandon route?" confirmation
- [ ] **PX-04**: Guidance supports fullscreen and the screen remains usable in landscape (driving posture)

### Design Fidelity & Privacy Promise

- [x] **DSGN-01**: All screens render from a centralized Telemetry Rams token set (palette, type, spacing, radius-0) — no off-token values; map basemap cartography follows the same tokens
- [x] **DSGN-02**: Each UI phase produces a mockup-vs-implementation gallery comparison reviewed for fidelity before proceeding
- [x] **PRIV-01**: The privacy promise is visible in-product: /privacy command plus in-app trip start/end messaging ("trip ended, data deleted")
- [x] **PRIV-02**: The backend holds no persistent per-user location history or profile — only TTL-expiring ephemeral state (privacy by construction, verifiable by architecture audit)

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Routing Extras

- **RGNG-01**: Toll vs toll-free route toggle (Valhalla use_tolls costing — engine already supports it)
- **RGNG-02**: Speed limit display where OSM maxspeed data exists ("show nothing rather than wrong values")
- **GUID-07**: Voice guidance — spoken turns via Web Speech API, mute-by-default, sendVoice fallback (gated on iOS webview TTS spike)
- **TRIP-01**: Live trip share via sendLocation(live_period) + editMessageLiveLocation with ETA — user-initiated, expires

### Reports & Social (v2 cluster)

- **REP-01**: User can report incidents (/accident, /traffic, /hazard) with location sharing
- **REP-02**: Nearby users receive concise incident broadcasts
- **OPTN-01**: Opt-in anonymized speed pings for aggregate traffic-weighted ETAs (seed of the v2 report crowd data)
- **GAME-01**: Minimalist gamification (points for validated reports, Rams-badge achievements)

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| In-app ads / sponsored POI pins | Breaks the brand promise on a driving surface; privacy-violating profiling |
| Engagement push notifications | Drive-away behavior for a privacy brand; only transactional messages ship |
| Persistent accounts / contact requests | Telegram identity is the only identity; never requestContact() |
| Offline maps product | Contrary to the Telegram-first premise; in-session prefetch only (v1.x candidate) |
| "AI assistant" flavored onboarding | Deterministic commands are the model; Rams simplicity |
| Group/location echo broadcasts | Crosses privacy boundaries of non-consenting users |
| Ops-stack services (RabbitMQ, PostGrafana monitoring, Resend) | Stripped for v1 — no producer/user for them before reports exist |
| Regional clusters / carpool groups | Unvalidated social hypothesis per PROJECT.md |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| DSGN-01 | Phase 1 | Complete |
| DSGN-02 | Phase 1 | Complete |
| ONBD-01 | Phase 2 | Complete |
| PRIV-01 | Phase 2 | Complete |
| PRIV-02 | Phase 2 | Complete |
| GEO-01 | Phase 3 | Complete |
| GEO-02 | Phase 3 | Complete |
| GEO-03 | Phase 3 | Complete |
| PX-02 | Phase 3 | Complete |
| SRCH-01 | Phase 4 | Pending |
| SRCH-02 | Phase 4 | Pending |
| SRCH-03 | Phase 4 | Pending |
| ONBD-02 | Phase 4 | Pending |
| ONBD-03 | Phase 4 | Pending |
| RTNG-01 | Phase 5 | Pending |
| RTNG-02 | Phase 5 | Pending |
| GUID-01 | Phase 6 | Pending |
| GUID-02 | Phase 6 | Pending |
| GUID-03 | Phase 6 | Pending |
| GUID-04 | Phase 6 | Pending |
| GUID-05 | Phase 6 | Pending |
| GUID-06 | Phase 6 | Pending |
| PX-01 | Phase 6 | Pending |
| PX-03 | Phase 6 | Pending |
| PX-04 | Phase 7 | Pending |

**Coverage:**
- v1 requirements: 22 total
- Mapped to phases: 22 ✓
- Unmapped: 0

Staging notes (each requirement maps to exactly one owning phase):
- PRIV-01: /privacy command delivered in Phase 2; the in-app "trip ended, data deleted" messaging completes at the trip boundary in Phase 6 (success criterion there).
- PX-01 (BackButton full state walk) and PX-03 (safe areas, swipe-close, abandon confirmation): shell grounding built in Phase 3; observable behaviors owned by Phase 6 where the full state graph exists.

---
*Requirements defined: 2026-10-22*
*Last updated: 2026-10-22 — roadmap created, traceability filled (22/22 mapped)*