Bookmarks (Saved Results) Architecture
Modul Bookmarks (secara internal diimplementasikan sebagai Saved Results) mengelola penyimpanan persisten, organisasi hierarkis berbasis folder, dan sinkronisasi CloudKit untuk hasil pencarian kitab di aplikasi Maktabah. Modul ini memungkinkan pengguna menyimpan kueri pencarian beserta referensi kitab dan halaman yang cocok ke dalam struktur direktori hierarkis kustom.
1. Arsitektur & Diagram Alur (Architecture & Pipeline)
Arsitektur modul ini dibangun menggunakan pola MVVM dengan persistensi lokal SQLite dan sinkronisasi CloudKit dua arah:
flowchart TD
MAC["SavedResults (macOS)"] --> RVM["ResultsViewModel (@Observable)"]
IOS["iOSSavedResultsView (iOS)"] --> RVM
DB["ResultsHandler"]
SYNC["CloudKitSyncManager (ResultSyncHandler)"]
MD["LibraryDataManager (Book Metadata Lookup)"]
RVM -->|"Upsert / Load"| DB
RVM -->|"Sync CloudKit"| SYNC
RVM -->|"Join Book Metadata"| MD
DB --> SQLite[("SearchResults.sqlite (WAL Mode)")]
SYNC <-->|"Fetch / Upload"| CloudKit[("CloudKit Custom Zone")]
classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;
class MAC,IOS ui;
class RVM vm;
class DB,SYNC,MD store;
class SQLite,CloudKit db;
2. Pemisahan Tanggung Jawab (Separation of Concerns)
Komponen-komponen dalam modul ini mematuhi batas tanggung jawab yang tegas:
-
UI Layer (macOS & iOS):
- Mengatur visualisasi representasi hierarki direktori (folder dan item hasil pencarian).
- Platform macOS (
SavedResults,ResultsViewManager) mengonsumsiBookmarkTreeChangeuntuk mengeksekusi animasi batch padaNSOutlineView(insertItems,removeItems,moveItem). - Platform iOS (
iOSSavedResultsView,iOSFolderContentList) memanfaatkan deklarasi hierarki berbasisNavigationStack, swipe actions, dan sheet navigasi interaktif.
-
ViewModel Layer (
ResultsViewModel):- Berperan sebagai single source of truth untuk antarmuka pengguna pada kedua platform.
- Memelihara cache struktural dalam memori (
folderById,parentById,resultById) untuk lookup $O(1)$ selama pembaruan parsial. - Mencegah siklus tak berujung (circular dependency) pada operasi pemindahan folder (drag-and-drop).
-
Data Access Layer (
ResultsHandler):- Mengisolasi seluruh kueri SQL, migrasi skema tabel, dan eksekusi transaksi basis data
SearchResults.sqlite. - Menangani resolusi orphan records akibat perbedaan urutan penerimaan data sinkronisasi CloudKit.
- Mencatat mutasi luring ke dalam
SyncPendingStore.
- Mengisolasi seluruh kueri SQL, migrasi skema tabel, dan eksekusi transaksi basis data
-
Synchronization Layer (
CloudKitSyncManager):- Menerjemahkan rekaman lokal ke
CKRecorddengan penamaan ID deterministik. - Menjalankan resolusi konflik Last-Write-Wins (LWW) berbasis stempel waktu
lastModified.
- Menerjemahkan rekaman lokal ke
3. Peta Navigasi Dokumentasi Teknis
- Database & CloudKit Persistence
- Skema SQLite, indeks unik gabungan, isolasi thread
SQLiteDatabase, pemulihan orphan records, dan sinkronisasi CloudKit.
- Skema SQLite, indeks unik gabungan, isolasi thread
- Data Models & State Types
- Struktur data hierarki, result node, model sinkronisasi, dan tree diffing.
- iOS SwiftUI Implementation
- Integrasi
NavigationStack, pencarian global mendatar (flattened search), pengelolaan lembar pemindahan (move sheet), dan gestur geser (swipe actions).
- Integrasi
- macOS AppKit Implementation
- Implementasi
NSOutlineView, animasi diffing presisi tinggi (batch updates), drag-and-drop antar-hierarki, dan menu kontekstual.
- Implementasi
- Protocols & Delegation
- Kontrak komunikasi
@MainActor ResultsDelegateuntuk menghubungkan pemilihan markah ke modul Reader/Search.
- Kontrak komunikasi
- ViewModel & Reactive Workflows
- Manajemen state berbasis
@Observable, cache lookup $O(1)$, operasi rekursif hierarki, dan integrasi notifikasi.
- Manajemen state berbasis