133 lines
7.5 KiB
Markdown
133 lines
7.5 KiB
Markdown
# 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)
|
|
- [x] **ONBD-02**: User can open the Mini App from a search result with their destination preloaded (no re-entry in the webview)
|
|
- [x] **ONBD-03**: User can add araharah to their phone home screen and launch search/navigation from there (addToHomeScreen + startapp deep-link)
|
|
|
|
### Destination Search
|
|
|
|
- [x] **SRCH-01**: User can type a destination query (e.g. "KLCC") and receive a shortlist containing the right KL-metro landmark/POI
|
|
- [x] **SRCH-02**: User gets useful results despite abbreviations and typos (Jln↔Jalan, Tmn↔Taman, missing spaces, common Malay address shorthand)
|
|
- [x] **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
|
|
|
|
- [x] **RTNG-01**: User sees a calculated route from current location to destination drawn on a Rams-styled map (grayscale grounding, accent route)
|
|
- [x] **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
|
|
|
|
- [x] **GUID-01**: While driving, the user sees a prominent next-maneuver banner (distance + arrow + street name) and a collapsible full maneuver list
|
|
- [x] **GUID-02**: After a missed turn, the app detects it and auto-recalculates from the current position without asking or blaming
|
|
- [x] **GUID-03**: The user sees ETA and remaining distance progress with each location fix (honest, self-paced ETA — no fake traffic confidence)
|
|
- [x] **GUID-04**: Guidance surfaces haptic cues at maneuver points (eyes-free, voice-free v1)
|
|
- [x] **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
|
|
- [x] **GUID-06**: Re-opening the Mini App mid-trip resumes live guidance seamlessly at the user's progressed position
|
|
|
|
### Platform Hygiene (Mini App)
|
|
|
|
- [x] **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
|
|
- [x] **PX-03**: During guidance, safe areas are respected, vertical-swipe-close is disabled, and closing shows the "abandon route?" confirmation
|
|
- [x] **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 | Complete |
|
|
| SRCH-02 | Phase 4 | Complete |
|
|
| SRCH-03 | Phase 4 | Complete |
|
|
| ONBD-02 | Phase 4 | Complete |
|
|
| ONBD-03 | Phase 4 | Complete |
|
|
| RTNG-01 | Phase 5 | Complete |
|
|
| RTNG-02 | Phase 5 | Complete |
|
|
| GUID-01 | Phase 6 | Complete |
|
|
| GUID-02 | Phase 6 | Complete |
|
|
| GUID-03 | Phase 6 | Complete |
|
|
| GUID-04 | Phase 6 | Complete |
|
|
| GUID-05 | Phase 6 | Complete |
|
|
| GUID-06 | Phase 6 | Complete |
|
|
| PX-01 | Phase 6 | Complete |
|
|
| PX-03 | Phase 6 | Complete |
|
|
| PX-04 | Phase 7 | Complete |
|
|
|
|
**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)*
|