Rah E Zair · راہِ زائر

A digital companion for Ziyarat — your guide on the path of pilgrimage.

Holy-site encyclopedia · location-aware smart guide · duas & ziyarat · guided pilgrimage · prayer times & qibla · offline-first · multilingual (EN / العربية / اردو)

---

What this is (and what it isn't yet)

The full vision is enormous — a scholar-reviewed encyclopedia of every major pilgrimage site on earth, indoor beacon navigation, offline map tiles, a RAG AI in a dozen languages, crowd analytics, group mode. That is a multi-year, multi-team, content-heavy product.

This repository is a working Phase-1 foundation that already runs on web, Android and iOS and demonstrates the signature experiences end-to-end. It is built so the vision can grow into it — the hard architecture (geofencing engine, offline-first data model, on-device prayer astronomy, retrieval AI, i18n + RTL, a scholarly-review workflow baked into the data) is here.

On the religious content: every historical and devotional item ships marked “Pending scholarly review.” The app shows that status rather than hiding it. The included Arabic supplications are widely-known, centuries-old public-domain phrases with plain functional translations written for this project; the coordinates are approximate public references. Nothing here should be presented to pilgrims as authoritative until a qualified scholarly board has verified it. This discipline is a feature, not a placeholder.

---

Features in this build

Area	What works today
Holy-site encyclopedia	Karbala & Najaf — Imam Husayn, Al-Abbas, Imam Ali. Each with history, timeline, etiquette, facilities (wheelchair / water / women's area / photography), micro-zones and recommended duas.
Smart Guide (geofencing)	Real Haversine + bearing engine resolves which site and which micro-zone you're in and surfaces the right dua — “You are at: the Zarih.” Uses live GPS on device; a location simulator lets you demo it anywhere.
Guided Pilgrimage mode	A step-by-step wizard: prepare → approach → enter → recite → pray → depart, each step with its dua.
Duas & Ziyarat library	Arabic, transliteration and translation, bookmarking, filter by type, with an audio hook (speech-synthesis stub until recitation files land).
Prayer times & Qibla	Computed on-device from solar geometry (no API, works offline), with Jafari / MWL / ISNA methods, a high-latitude night-fraction rule (no broken times in northern summers), timezone-correct countdowns, and a live compass Qibla dial (with the iOS permission flow).
Assistant	Retrieval-first in all three languages (Unicode tokenizer with Arabic normalization): answers only from the app's reviewed content and always cites its sources. Works fully offline; an optional grounded LLM can phrase answers (VITE_AI_URL, with timeout + error handling).
Offline-first	A service worker precaches the entire app — including self-hosted Arabic/Latin fonts — so the web/PWA build works with no network at all. All content ships bundled (no fake “downloads”); data persists locally and, on phones, into native storage (SharedPreferences / UserDefaults) so the OS can't evict it.
Journey tools	Visited-sites progress ring, personal journal, bookmarks.
Accessibility & i18n	English, Arabic and Urdu with full RTL; Night & Sepia themes; large-text mode.

---

Architecture

src/
  types.ts            data model — every claim carries a review status
  data/               cities, holy sites, micro-zones, duas, guided routes
  lib/
    geo.ts            Haversine distance, bearing, geofence resolver
    prayer.ts         solar prayer-time astronomy + qibla (offline)
    ai.ts             retrieval corpus + optional grounded LLM
    store.ts          local persistence + durable native mirror
    native.ts         Capacitor storage bridge
  i18n.ts             EN / AR / UR strings + RTL
  screens/            Home · Explore · SiteDetail · SmartGuide ·
                      GuidedMode · Duas · Prayer · Assistant · More

Stack: React 18 · TypeScript · Vite · hand-rolled CSS · Capacitor 8 (native Android/iOS). No backend required for the core; a backend + real map tiles + beacons come with later phases.

The PRD proposes Flutter; this MVP uses React + Capacitor because it produces installable Android and iOS apps from one codebase and a first-class web/PWA build, which suits an offline-first, content-driven app. The data model and algorithms port cleanly if a Flutter rewrite is chosen later.

---

Run it

npm install
npm run dev          # http://localhost:5174
npm test             # Vitest: prayer astronomy, geofencing, multilingual retrieval
npm run build        # static build in dist/ (installable offline PWA)

Or just use it: smafnan.github.io/Rah-E-Zair — installable (Add to Home Screen) and fully offline after first load. Android: download the APK (debug-signed — allow “install unknown apps”). CI builds the APK on every v* tag.

Deep-links for any screen (used for the screenshots above): ?screen=guide&at=karbala-husayn, ?screen=site&param=najaf-ali, ?screen=prayer.

Android

npm run build && npx cap sync && npx cap open android   # → Run ▶ in Android Studio

iOS (needs a Mac + Xcode)

npm run build && npx cap sync && npx cap open ios        # → set signing team → Run ▶

Optional grounded AI

Point VITE_AI_URL (in a .env) at an endpoint that accepts {question, context, system} and returns {answer}. Without it, the assistant answers offline from cited passages.

---

The content pipeline (the real work)

The engineering here is the easy 20%. The 80% is a verified, scholar-reviewed content database. The data model is deliberately structured for that workflow:

• every HolySite, MicroZone and Dua has a review field (draft → needs-review → verified);
• UI strings ship in EN/AR/UR (written functionally for this project — a native-speaker review pass is part of the content pipeline);
• sources arrays are present but intentionally empty until scholars populate them;
• content is localized (I18nText) from the start;
• coordinates are flagged as needing an on-site survey (and beacons/QR indoors).

A production rollout needs: a scholarly editorial board, source citation for every claim, transparent handling of differing opinions, survey-grade geodata, professional translations, and licensed or newly-recorded audio recitations.

Roadmap

• Phase 1 (this repo): accounts-free MVP · Karbala & Najaf · encyclopedia · geofencing · guided mode · prayer times & qibla · offline data · retrieval assistant · EN/AR/UR.
• Phase 2: Kufa · Kadhimayn · Samarra · Mashhad · Qom · Damascus · indoor beacons/QR · offline map tiles (MapLibre + OSM) · group mode · cloud accounts & sync · more languages.
• Phase 3: Mecca · Medina · global heritage sites · computer-vision landmark recognition · crowd analytics · wearables · on-device offline AI.

---

بِسْمِ اللّٰهِ — built with respect for the significance of each site.