# 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](file:///Users/dwindown/CascadeProjects/jamshalat-diary/lib/app/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](file:///Users/dwindown/CascadeProjects/jamshalat-diary/lib/app/router.dart#174-259) and [AppBottomNavBar](file:///Users/dwindown/CascadeProjects/jamshalat-diary/lib/core/widgets/bottom_nav_bar.dart#10-108) 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:

```dart
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 |