Islam Sunnah

Offline-first Quran, Hadith, and prayer companion — bundled as a Flutter app for Android, iOS, Web, macOS, Windows, and Linux.

Why This Exists

Most Islamic apps require a network connection to read Quran or Hadith. This one bundles the complete Quran (114 surahs, ~5MB) and Sahih Al-Bukhari (~2,400 hadiths, ~8MB) as local JSON assets — zero API calls for core content. The trade-off is a larger install size (worth it for availability in areas with poor connectivity).

What It Does

• Quran reader — All 114 surahs with Arabic, English, and Indonesian translations. Audio recitation, bookmarking, last-read tracking.
• Hadith library — Full Sahih Al-Bukhari collection. Read, search, bookmark, play audio.
• Daily verse & hadith — Fresh content each day, cached in SharedPreferences. Rotates at midnight, not mid-session.
• Duas & Zikr — 12 categories of supplications (morning, evening, travel, food, protection, etc.).
• Prayer times — Daily schedule with current/next prayer indicator, Hijri date, mosque locator. Adjustable per-prayer offsets.
• Q&A — Categories of Islamic questions with community answer cards and submission flow.
• Stories — Page-view reader for Prophet stories, Sahabah biographies, Hadith lessons, Islamic history.
• Settings — Reciter selection, font size, night mode, notification toggles, per-prayer Athan sound picker.

Architecture

Feature-grouped presentation layer over a service layer, stitched with Riverpod and GoRouter. Data flows one way: JSON assets → Service → Riverpod Provider → Screen.

lib/
├── main.dart
├── screens/          # 9 feature groups, 28 screens total
│   ├── auth/         # Sign in, sign up, password reset, OTP verification
│   ├── home/         # Dashboard with daily content and feature shortcuts
│   ├── quran/        # Surah index + verse reader with audio controller
│   ├── hadith/       # Collection index + hadith reader
│   ├── dua/          # Category grid + supplication detail
│   ├── prayer/       # Prayer times + mosque details
│   ├── question_and_answer/
│   ├── stories/      # Category grid + PageView reader
│   └── settings/     # Profile, bookmarks, notifications, preferences
├── services/         # JSON loader, daily content engine, audio playback
├── models/           # Surah, Verse, Hadith, DailyVerse, DailyHadith
├── widgets/          # Reusable components by feature and type
└── utils/            # GoRouter config, theme, color constants, asset paths

Key decisions: Riverpod over BLoC (less boilerplate, compile-safe providers), GoRouter with static path/name per screen (type-safe navigation), no DI framework (services exposed as simple Riverpod Provider singletons).

Getting Started

Prerequisites

• Flutter SDK >=3.6.1
• Dart >=3.6.1

Installation

git clone https://github.com/joshuacreator/islam_sunnah.git
cd islam_sunnah
flutter pub get

Run

flutter run -d chrome      # Web
flutter run -d ios          # iOS simulator
flutter run -d android      # Android device/emulator
flutter run -d macos        # macOS desktop

No build_runner steps, no environment variables, no API keys.

Testing

Tests are not yet written. The project has flutter_test as a dev dependency but no test/ directory. To add and run tests:

flutter test

Platform Support

Platform	Status	Notes
Android	✅	APK builds, runs on API 21+
iOS	✅	Builds with Xcode 15+
Web	✅	Full functionality
macOS	✅	Desktop build
Windows	✅	Desktop build
Linux	✅	Desktop build

Known Limitations

• Auth is UI-only — Login, signup, password reset, and OTP screens navigate on button press without any backend validation.
• Bookmarks not persisted — toggleBookmark() returns hardcoded values. No local or remote storage is wired.
• Last-read position not persisted — Progress resets on app restart.
• Search is placeholder — Search bars exist in Quran and Hadith screens but onSearchPressed callbacks are no-ops.
• Placeholder data — User profiles, mosque locations, Q&A content, and stories are hardcoded examples.
• No CI/CD — No automated build, test, or lint check pipeline.
• No analytics or crash reporting — Zero telemetry, for better and worse.

Contributing

Open an issue for bugs or feature requests. PRs welcome — match existing code style (flutter analyze to lint) and add tests where possible. No formal code of conduct yet.

License

MIT. See LICENSE.