jamshalat-diary/handoff.md

Jamshalat Diary — Handoff Document

Last updated: 2026-03-15

---

Current State

The app is a Flutter-based Islamic daily companion with two operating modes:

• Mode Lengkap — Full features with 5 tabs: Beranda, Jadwal, Ibadah, Laporan, Alat
• Mode Simple — Streamlined with 5 tabs: Beranda, Jadwal, Tilawah, Murattal, Zikir

Routing Architecture

Routes are defined in router.dart. Key design:

• Dual route paths — Quran, Murattal, and Dzikir each exist as:
  • Top-level routes (/quran, /dzikir) for Simple Mode bottom bar tabs
  • Nested routes (/tools/quran, /tools/dzikir) for Full Mode Alat sub-screens
• parentNavigatorKey: _rootNavigatorKey — Used on routes that should hide the bottom nav bar (settings, qibla, murattal playback, all /tools/* sub-screens)
• isSimpleModeTab flag — Passed to screen widgets to control back button visibility
• ValueListenableBuilder — Wraps _ScaffoldWithNav and AppBottomNavBar to reactively update tabs when mode is toggled

⚠️ Critical: Hive Key Convention

Settings are stored under the Hive key 'default', NOT HiveBoxes.settings. This was a bug that was fixed across 7 files. Always use:

box.get('default')?.simpleMode ?? false;

Completed Features (Steps 1–13)

Step	Feature
1	myQuran Sholat API integration + Hive caching
2	EQuran.id API for Quran list, reading, audio, Ayat Hari Ini
3	Full Bahasa Indonesia localization
4	Ibadah Harian revamp (ShalatLog, TilawahLog, DzikirLog, PuasaLog)
5	UX/UI polish (Rawatib info, Kiblat compass, AppBar consistency)
6	Gamification point system
7	Tilawah active session tracker with cross-surah diff
8	Quran bookmarks (Last Read + Favorit Ayat)
9	Per-ayat audio playback
10	Full surah Murattal player with Qari selector
11	Murattal playlist navigation + auto-play next
12	Mode Hafalan (loop ayat range)
13	Murattal screen enhancements
—	Simple Mode / Full Mode dynamic routing
—	Lucide Icons migration
—	Live search debouncer
—	Bottom nav bar dynamic tabs

---

New API: muslim.backoffice.biz.id

Base URL: https://muslim.backoffice.biz.id

A. Replacement — Migrate Data Sources

Replace current EQuran.id and local JSON with the user's own API for better control and reliability.

Current Source	New Endpoint	Notes
EQuran.id Surah list	GET /v1/quran/surah	Includes audio_url (Mishari Alafasy)
EQuran.id Ayat per surah	GET /v1/quran/ayah/surah?id={surahId}	Arab, latin, translation, per-ayat audio, juz, page, hizb
Local dzikir JSON	GET /v1/dzikir?type={pagi|sore|solat}	Adds Dzikir Sesudah Sholat
EQuran.id random ayat	GET /v1/quran/ayah/specific?surahId=X&ayahId=Y	For Ayat Hari Ini

B. Enrichment — Enhance Existing Screens

Feature	Endpoint	Where
Tafsir Kemenag	GET /v1/quran/tafsir	New tab on Quran Reading screen
Kata Per Kata (word-by-word)	GET /v1/quran/word/ayah?surahId=X&ayahId=Y	Toggle in Quran Reading screen
Browse by Juz	GET /v1/quran/juz	Option in Tilawah screen
Browse by Page (Mushaf)	GET /v1/quran/ayah/page?id={pageId}	Option in Tilawah screen
Asbabun Nuzul	GET /v1/quran/asbab	Inline on verses that have asbab reference
Asmaul Husna	GET /v1/quran/asma	Mini-feature in Alat/Beranda
Quran Theme index	GET /v1/quran/theme	Browse by Topic in Tilawah
Quran Search by meaning	GET /v1/quran/ayah/find?query={word}	Search bar in Tilawah screen

C. New Screens

Each new screen should be:

• Added to the Alat screen grid in Full Mode
• Listed in the Beranda Quick Actions in Simple Mode
• Routed under /tools/{feature} (Full Mode, hides bottom bar) and optionally as a top-level route for Simple Mode

Screen	Endpoint	Description
Kumpulan Doa	GET /v1/doa	Categorized prayers (quran, hadits, harian, ibadah, haji, etc.) with search via /v1/doa/find?query=X
Hadits Arba'in	GET /v1/hadits	42 Hadits with Arabic + Indonesian, searchable via /v1/hadits/find?query=X

---

Implementation Priority

Phase 1: API Service Layer

• Create muslim_api_service.dart in lib/data/services/
• Base URL: https://muslim.backoffice.biz.id
• Implement HTTP client with error handling + caching pattern (similar to equran_service.dart)

Phase 2: Replacement (migrate data sources)

• Migrate Surah listing to /v1/quran/surah
• Migrate Ayat reading to /v1/quran/ayah/surah?id=X
• Migrate Murattal audio URLs to new API audio_url field
• Migrate Dzikir data from local JSON to /v1/dzikir?type=X
• Add Dzikir Sesudah Sholat category

Phase 3: Enrichment

• Quran Tafsir tab on reading screen
• Kata Per Kata toggle on reading screen
• Juz browser in Tilawah
• Quran search by meaning
• Asbabun Nuzul inline display
• Asmaul Husna mini-feature

Phase 4: New Screens

• Kumpulan Doa screen + route + Alat grid entry + Beranda quick action
• Hadits Arba'in screen + route + Alat grid entry + Beranda quick action

---

Key Files Reference

File	Purpose
lib/app/router.dart	All navigation routes, dual-path routing, bottom nav logic
lib/core/widgets/bottom_nav_bar.dart	Dynamic bottom nav tabs (ValueListenableBuilder)
lib/features/dashboard/presentation/dashboard_screen.dart	Beranda with Quick Actions
lib/features/tools/presentation/tools_screen.dart	Alat grid
lib/features/settings/presentation/settings_screen.dart	Mode toggle (saves to Hive key 'default')
lib/data/local/hive_boxes.dart	Hive initialization + seed defaults
lib/data/local/models/app_settings.dart	Settings model with simpleMode field
lib/data/services/equran_service.dart	Current Quran API client (to be replaced)
lib/features/quran/presentation/quran_screen.dart	Tilawah screen
lib/features/quran/presentation/quran_reading_screen.dart	Quran reading
lib/features/quran/presentation/quran_murattal_screen.dart	Murattal player
lib/features/dzikir/presentation/dzikir_screen.dart	Dzikir counter