iQuran: Worldwide Quran Companion Islamic App

Niche: Faith tech / accessible religious education Client: ICNA / WhyIslam (877-Why-Islam) — whyislam.org · icna.org Status: Live worldwide — App Store · Play Store Role: Senior Flutter Engineer / Software Architect — full product build, architecture, and store launch Stack: Flutter (single codebase: Android, iOS, Web, Windows), Firebase (Auth, Firestore, Storage, App Check), just_audio + audio_service, MapLibre GL / Google Maps, geolocator, sensors_plus

Most Quran apps are built for an audience that is already Muslim and already reads Arabic. The interfaces assume prior religious literacy, translations are often archaic or academic, and onboarding presumes the user knows what a Surah, Juz, or Qibla is. For the two audiences WhyIslam serves — non-Muslims curious about Islam and non-Arabic-speaking Muslims (including new converts) — there was no welcoming, zero-cost, ad-free entry point to the Quran.

ICNA's WhyIslam program (the team behind the 877-Why-Islam hotline) needed a digital companion that could meet a complete beginner where they are: clear English, guided audio, practical daily tools, and no paywall anywhere.

A completely free, worldwide Quran companion designed first for the first-time reader:

All 114 Surahs with an authentic English translation chosen and presented for clarity, not academic density

Audio recitation with background playback — listen on the lock screen, in the car, or while the phone is in your pocket

Hifz mode — playlists with repeat controls for memorization

A practical daily-life layer (prayer times, Qibla, masjid finder, Hijri calendar) so the app grows with the user from "curious reader" to "daily practice"

A Become Muslim / Revert educational section connecting users directly to WhyIslam's outreach resources

Quran Reader — Indopak Arabic script with a custom bundled font, Surah/Juz/page navigation, multilingual translations with caching, advanced search, bookmarks, dark mode, and full offline reading

Recitation Engine — multiple reciters, playlist creation and management, continuous playback across Surahs, lock-screen and notification controls, Android Auto-ready architecture

My Quran Journey — personal reading-progress tracking with streaks, goals, and reading-reminder notifications to build a daily habit

Prayer Suite — geolocation-based prayer times with multiple calculation methods, Adhan notifications, magnetometer-driven Qibla compass, Islamic/Hijri calendar, and the 99 Names of Allah

Masjids Nearby — GPS map-based mosque discovery

Accounts & Sync — Firebase Auth with Google Sign-In and Sign in with Apple, cross-device sync, full guest mode (no account required to read), profile management, in-app feedback, and a "Gift a Quran" donation flow

Repository-pattern architecture — clean separation between Firestore data sources, caching layers, and UI, applied consistently across 10+ feature repositories. Each feature (Quran, prayer, audio, journey, masjids) is an isolated module under lib/.

Custom background-audio handler — instead of relying on just_audio_background (which had plugin-registration conflicts with audio_service), I wrote a custom QuranAudioHandler extending BaseAudioHandler, giving full control over lock-screen controls, playlist-scoped playback, and cross-Surah continuity.

Permission-respectful location flow — getPrayerTimesIfPermitted() checks permission status without prompting, falling back to cache or null. The user is never ambushed with a system dialog — a deliberate UX decision for an audience that may be cautious about a religious app requesting location.

Production-grade error pipeline — FlutterError.onError, ErrorWidget.builder, and PlatformDispatcher.instance.onError are all wired with stack_trace demangling, so even web JS stack traces resolve back to Dart file:line:col for source-accurate production diagnostics.

Multi-target Firebase setup — including a web-only conditional registrar (firebase_web_registrar_stub.dart / _web.dart via dart.library.html) to keep mobile builds clean while supporting four platforms from one codebase.

Release polish — native splash, cross-platform launcher icons generated from a single config, custom theming, version-check enforcement, and Firebase App Check securing the backend.

Live on both major stores, distributed free worldwide with no ads or paywalls

Replaces what would normally require 3–4 separate apps (reader, audio player, prayer times, mosque finder) with one cohesive, beginner-friendly experience

Serves ICNA/WhyIslam's outreach mission as the official digital companion to the 877-Why-Islam program