fix(mobile): resolve cache sync issues and modularize notes API

Author: batalabs

apps/mobile/v1/src/screens/FolderNotes/components/NotesList/NoteListItem.tsx

@@ -286,7 +286,7 @@ const styles = StyleSheet.create({
     flexDirection: 'row',
     alignItems: 'center',
     justifyContent: 'space-between',
-    marginBottom: 6,
+    marginBottom: 8,
   },
   noteListTitle: {
     fontSize: 17,
@@ -315,14 +315,14 @@ const styles = StyleSheet.create({
   },
   noteListPreview: {
     fontSize: 15,
-    lineHeight: 20,
-    marginBottom: 4,
+    lineHeight: 22,
+    marginBottom: 6,
   },
   noteListFolderInfo: {
     flexDirection: 'row',
     alignItems: 'center',
     gap: 6,
-    marginTop: 4,
+    marginTop: 6,
   },
   noteListFolderDot: {
     width: 8,
@@ -338,6 +338,7 @@ const styles = StyleSheet.create({
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     height: StyleSheet.hairlineWidth,
     marginHorizontal: 16,
+    marginVertical: 0,
   },
   deleteAction: {
     backgroundColor: '#ef4444',

apps/mobile/v1/src/screens/FolderNotes/components/NotesList/index.tsx

@@ -1,9 +1,9 @@
-import { Ionicons } from '@expo/vector-icons';
 import { useUser } from '@clerk/clerk-expo';
+import { Ionicons } from '@expo/vector-icons';
 import { BottomSheetModal } from '@gorhom/bottom-sheet';
-import { FlashList } from '@shopify/flash-list';
 import AsyncStorage from '@react-native-async-storage/async-storage';
 import { useFocusEffect } from '@react-navigation/native';
+import { FlashList, type FlashList as FlashListType } from '@shopify/flash-list';
 import * as Haptics from 'expo-haptics';
 import { useRouter } from 'expo-router';
 import React, { useCallback,useEffect, useMemo, useRef, useState } from 'react';
@@ -97,7 +97,7 @@ export default function NotesList({ navigation, route, renderHeader, scrollY: pa
   const createFolderSheetRef = useRef<BottomSheetModal>(null);
   const filterSortSheetRef = useRef<BottomSheetModal>(null);
   const noteActionsSheetRef = useRef<NoteActionsSheetRef>(null);
-  const flatListRef = useRef<FlashList<Note>>(null);
+  const flatListRef = useRef<FlashListType<Note>>(null);
 
   // Scroll tracking for animated divider (use parent's scrollY if provided)
   const localScrollY = useRef(new Animated.Value(0)).current;
@@ -592,10 +592,9 @@ export default function NotesList({ navigation, route, renderHeader, scrollY: pa
         data={filteredNotes}
         renderItem={renderNoteItem}
         keyExtractor={(item) => item.id}
-        estimatedItemSize={108}
         ListHeaderComponent={renderListHeader}
         ListEmptyComponent={renderEmptyComponent}
-        ListFooterComponent={<View style={{ height: 100 }} />}
+        ListFooterComponent={<View style={{ height: 120 }} />}
         showsVerticalScrollIndicator={false}
         onScroll={Animated.event(
           [{ nativeEvent: { contentOffset: { y: scrollY } } }],
@@ -616,8 +615,9 @@ export default function NotesList({ navigation, route, renderHeader, scrollY: pa
           return 'note';
         }}
         overrideItemLayout={(layout, item) => {
-          // Fixed layout for all items
-          layout.size = 108;
+          // Fixed layout for better scrolling performance
+          // Padding: 12*2=24, Header: 23+8, Preview: 40+6, Meta: 20, Divider: 1
+          layout.size = 112;
         }}
       />
 

apps/mobile/v1/src/screens/FolderNotes/components/NotesList/useNotesLoader.ts

@@ -302,7 +302,16 @@ export function useNotesLoader({
       const cacheAge = Date.now() - cacheTimestampRef.current;
       const cacheIsFresh = cacheLoadedRef.current && cacheAge < 30000; // 30 seconds
 
-      if (cacheIsFresh && cachedNotesRef.current.length > 0) {
+      // CRITICAL: Verify cache count matches API result count
+      // If counts differ, fresh data is available (new note created, note deleted, etc.)
+      // In this case, skip ultra-fast mode and use the fresh API data
+      const cacheCountMatches = cachedNotesRef.current.length === sortedNotes.length;
+
+      if (!cacheCountMatches && cacheIsFresh) {
+        console.log(`[PERF ⚡⚡⚡] SKIPPING ULTRA FAST MODE: Cache count mismatch (cached: ${cachedNotesRef.current.length}, API: ${sortedNotes.length}) - using fresh data`);
+      }
+
+      if (cacheIsFresh && cachedNotesRef.current.length > 0 && cacheCountMatches) {
         console.log(`[PERF ⚡⚡⚡] ULTRA FAST MODE: Cache is ${(cacheAge / 1000).toFixed(1)}s old - SKIPPING ALL DECRYPTION!`);
         console.log(`[PERF ⚡⚡⚡] Using ${cachedNotesRef.current.length} cached notes directly - INSTANT LOAD!`);
 

apps/mobile/v1/src/services/api/notes/README.md

@@ -0,0 +1,167 @@
+# Notes API - Modular Structure
+
+The notes API has been modularized to improve maintainability and make it easier to find and fix bugs.
+
+## Structure
+
+```
+services/api/notes/
+├── index.ts          # Main export, combines all modules
+├── crud.ts           # Create, update, delete operations (~400 lines)
+├── core.ts           # Query and other operations (to be further extracted)
+├── cache-sync.ts     # Cache synchronization utilities
+├── shared.ts         # Shared helper functions
+└── README.md         # This file
+```
+
+## Modules
+
+### `crud.ts` - Create, Update, Delete Operations
+**~400 lines** | ✅ Modularized
+
+Contains:
+- `createNote()` - Create new notes with offline support
+- `updateNote()` - Update existing notes with cache sync
+- `deleteNote()` - Delete notes
+
+**Key Features:**
+- Automatic cache synchronization (SQLite + AsyncStorage)
+- Offline support with optimistic updates
+- Proper error handling and logging
+
+### `cache-sync.ts` - Cache Synchronization
+**~50 lines** | ✅ Modularized
+
+Contains:
+- `updateSQLiteCache()` - Update local database cache
+- `clearAsyncStorageCaches()` - Clear preview caches
+- `syncAllCaches()` - Sync all cache layers
+
+**Purpose:** Centralized cache management to prevent stale data issues.
+
+### `shared.ts` - Shared Utilities
+**~40 lines** | ✅ Modularized
+
+Contains:
+- `invalidateCountsCache()` - Invalidate counts and database caches
+
+### `core.ts` - Core Operations
+**~1000 lines** | 🔄 To be further modularized
+
+Currently contains:
+- Query operations (`getNotes`, `getNote`, `getCounts`)
+- Visibility operations (`hideNote`, `unhideNote`)
+- Attachment operations (file upload/download)
+- Trash operations (`emptyTrash`)
+
+**Next Steps:** Extract these into separate modules:
+- `queries.ts` - Query operations
+- `visibility.ts` - Hide/unhide operations
+- `attachments.ts` - File operations
+
+## Benefits of Modularization
+
+### 1. Easier Bug Fixes
+**Before:** Search through 1269 lines to find delete logic
+**After:** Go directly to `crud.ts` (~400 lines)
+
+### 2. Better Code Organization
+Each module has a single responsibility:
+- CRUD operations → `crud.ts`
+- Cache management → `cache-sync.ts`
+- Shared utilities → `shared.ts`
+
+### 3. Easier Testing
+Each module can be tested independently:
+```typescript
+import { createCrudOperations } from './crud';
+// Test just CRUD operations
+```
+
+### 4. Cache Issue Resolution
+The cache synchronization bugs were caused by mixing cache logic throughout the file. Now it's centralized in `cache-sync.ts`, making it obvious when caches need to sync.
+
+## Cache Architecture
+
+The app has **3 cache layers:**
+
+1. **SQLite Database** (`databaseCache.ts`)
+   - Persistent local storage
+   - Survives app restarts
+   - Updated by: `updateSQLiteCache()`
+
+2. **AsyncStorage** (`useNotesLoader.ts`)
+   - UI preview cache
+   - Fast rendering
+   - Cleared by: `clearAsyncStorageCaches()`
+
+3. **In-Memory Refs** (`useNotesLoader.ts`)
+   - Ultra-fast mode (< 30 seconds)
+   - Skip decryption
+   - Auto-invalidated on count mismatch
+
+### Cache Sync Strategy
+
+**Create/Update Operations:**
+```typescript
+await syncAllCaches(note, shouldClearAsyncStorage);
+// 1. Always update SQLite cache
+// 2. Optionally clear AsyncStorage (for delete/archive/move)
+```
+
+**When to Clear AsyncStorage:**
+- ✅ Note deleted (`deleted: true`)
+- ✅ Note archived (`archived: true`)
+- ✅ Note moved to different folder (`folderId` changed)
+- ❌ Note content edited (keep cache for performance)
+
+## Migration Guide
+
+No changes needed! The modular structure maintains the same API:
+
+```typescript
+const api = useApiService();
+
+// All operations work the same
+await api.createNote({ title, content });
+await api.updateNote(noteId, { deleted: true });
+await api.deleteNote(noteId);
+```
+
+## Future Enhancements
+
+1. **Extract Remaining Modules:**
+   - [ ] `queries.ts` - Query operations
+   - [ ] `visibility.ts` - Hide/unhide operations
+   - [ ] `attachments.ts` - File operations
+
+2. **Add Unit Tests:**
+   - [ ] Test CRUD operations independently
+   - [ ] Test cache synchronization logic
+   - [ ] Mock network/database for faster tests
+
+3. **Performance Optimizations:**
+   - [ ] Batch cache updates
+   - [ ] Optimize background refresh
+   - [ ] Add request deduplication
+
+## Troubleshooting
+
+### "Deleted notes reappearing"
+**Root Cause:** Cache synchronization issue
+**Fixed in:** `crud.ts` + `cache-sync.ts`
+- `updateNote()` now syncs all caches
+- AsyncStorage cleared for location changes
+- SQLite always updated
+
+### "New notes not appearing"
+**Root Cause:** Ultra-fast mode using stale cache
+**Fixed in:** `useNotesLoader.ts`
+- Count mismatch detection
+- Skip ultra-fast mode if counts differ
+
+### "Notes showing [ENCRYPTED]"
+**Root Cause:** Background refresh storing encrypted content
+**Fixed in:** `core.ts`
+- Always cache decrypted content
+- Removed preference check

apps/mobile/v1/src/services/api/notes/cache-sync.ts

@@ -0,0 +1,58 @@
+/**
+ * Cache synchronization utilities
+ * Handles keeping SQLite and AsyncStorage caches in sync
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+import type { Note } from '../types';
+import { storeCachedNotes } from '../databaseCache';
+
+/**
+ * Update SQLite cache with a note after create/update
+ * This ensures the local database cache stays in sync with the server
+ */
+export async function updateSQLiteCache(note: Note): Promise<void> {
+  try {
+    await storeCachedNotes([note], { storeDecrypted: true });
+    if (__DEV__) {
+      console.log(`[CacheSync] ✅ Updated SQLite cache for note ${note.id}`);
+    }
+  } catch (error) {
+    console.warn('[CacheSync] Failed to update SQLite cache:', error);
+  }
+}
+
+/**
+ * Clear AsyncStorage preview caches
+ * Called when notes change location/status (delete, archive, move folder)
+ */
+export async function clearAsyncStorageCaches(): Promise<void> {
+  try {
+    const allKeys = await AsyncStorage.getAllKeys();
+    const noteCacheKeys = allKeys.filter(key => key.startsWith('notes-cache-v2-'));
+    if (noteCacheKeys.length > 0) {
+      await AsyncStorage.multiRemove(noteCacheKeys);
+      if (__DEV__) {
+        console.log(`[CacheSync] ✅ Cleared ${noteCacheKeys.length} AsyncStorage cache(s)`);
+      }
+    }
+  } catch (error) {
+    console.warn('[CacheSync] Failed to clear AsyncStorage caches:', error);
+  }
+}
+
+/**
+ * Sync all cache layers after a note operation
+ * @param note - The note to sync
+ * @param clearPreviewCaches - Whether to clear AsyncStorage caches (for delete/archive/move)
+ */
+export async function syncAllCaches(note: Note, clearPreviewCaches: boolean = false): Promise<void> {
+  // Always update SQLite cache
+  await updateSQLiteCache(note);
+
+  // Optionally clear AsyncStorage preview caches
+  if (clearPreviewCaches) {
+    await clearAsyncStorageCaches();
+  }
+}