forked from c-fu/arah2
7.5 KiB
7.5 KiB
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
- 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
- GEO-01: The Mini App can obtain the user's current location via Telegram LocationManager, with permission persisting across sessions
- GEO-02: When in-app location fails (denied permissions or Desktop Telegram without geolocation), the chat "send location" keyboard fallback obtains the origin
- 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
- 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
- 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
- DSGN-02: Each UI phase produces a mockup-vs-implementation gallery comparison reviewed for fidelity before proceeding
- PRIV-01: The privacy promise is visible in-product: /privacy command plus in-app trip start/end messaging ("trip ended, data deleted")
- 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)