@buivietphi/skill-mobile-mt 2.0.0

package/shared/offline-first.md

@@ -0,0 +1,377 @@
+# Offline-First — Mobile Data Strategy
+
+> On-demand. Load when: "offline", "offline-first", "cache", "sync", "local database", "persistence"
+> Source: Mattermost, Immich, Expensify, Ignite
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│  UI Layer (reads local only)        │
+└──────────────┬──────────────────────┘
+               │
+┌──────────────▼──────────────────────┐
+│  Repository Layer (sync logic)      │
+└──────┬──────────────────────┬───────┘
+       │                      │
+┌──────▼──────┐     ┌─────────▼───────┐
+│  Local DB   │◄───►│   Remote API    │
+│  (primary)  │     │   (sync only)   │
+└─────────────┘     └─────────────────┘
+```
+
+**Rule:** UI always reads local. API is sync-only, never primary.
+
+---
+
+## React Native — WatermelonDB (Reference Implementation)
+
+### Schema
+
+```typescript
+// db/schema.ts
+export const schema = appSchema({
+  version: 1,
+  tables: [
+    tableSchema({
+      name: 'posts',
+      columns: [
+        { name: 'title', type: 'string' },
+        { name: 'body', type: 'string' },
+        { name: 'author_id', type: 'string' },
+        { name: 'created_at', type: 'number' },
+        { name: 'updated_at', type: 'number' },
+        { name: 'is_synced', type: 'boolean' },
+        { name: 'is_deleted', type: 'boolean' },  // soft delete required for sync
+      ],
+    }),
+  ],
+});
+```
+
+### Model
+
+```typescript
+export default class Post extends Model {
+  static table = 'posts';
+  static associations = {
+    comments: { type: 'has_many', foreignKey: 'post_id' },
+  };
+
+  @field('title') title!: string;
+  @field('body') body!: string;
+  @field('author_id') authorId!: string;
+  @readonly @date('created_at') createdAt!: Date;
+  @field('updated_at') updatedAt!: number;
+  @field('is_synced') isSynced!: boolean;
+  @field('is_deleted') isDeleted!: boolean;
+
+  async markAsDeleted() {
+    await this.update(post => {
+      post.isDeleted = true;
+      post.isSynced = false;
+    });
+  }
+}
+```
+
+### Sync Engine
+
+```typescript
+export async function syncDatabase() {
+  await synchronize({
+    database,
+    pullChanges: async ({ lastPulledAt }) => {
+      const { changes, timestamp } = await api.get('/sync', {
+        params: { last_pulled_at: lastPulledAt },
+      });
+      return { changes, timestamp };
+    },
+    pushChanges: async ({ changes, lastPulledAt }) => {
+      await api.post('/sync', { changes, last_pulled_at: lastPulledAt });
+    },
+    migrationsEnabledAtVersion: 1,
+  });
+}
+
+export function startBackgroundSync() {
+  const interval = setInterval(syncDatabase, 30000);
+  AppState.addEventListener('change', state => {
+    if (state === 'active') syncDatabase();
+  });
+  return () => clearInterval(interval);
+}
+```
+
+### Repository
+
+```typescript
+export class PostRepository {
+  private posts = database.get<Post>('posts');
+
+  getAll() {
+    return this.posts.query(
+      Q.where('is_deleted', false),
+      Q.sortBy('created_at', Q.desc),
+    ).fetch();
+  }
+
+  observeAll() {
+    return this.posts.query(
+      Q.where('is_deleted', false),
+      Q.sortBy('created_at', Q.desc),
+    ).observe();
+  }
+
+  async create(data: { title: string; body: string; authorId: string }) {
+    return database.write(async () => {
+      return this.posts.create(post => {
+        Object.assign(post, data);
+        post.isSynced = false;
+        post.isDeleted = false;
+        post.updatedAt = Date.now();
+      });
+    });
+  }
+
+  async update(post: Post, data: Partial<{ title: string; body: string }>) {
+    return database.write(async () =>
+      post.update(p => { Object.assign(p, data); p.isSynced = false; p.updatedAt = Date.now(); })
+    );
+  }
+
+  async delete(post: Post) {
+    return database.write(async () => post.markAsDeleted());
+  }
+}
+```
+
+---
+
+## Flutter — Drift + Riverpod
+
+### Key differences from RN
+
+```dart
+// Table definition
+class Posts extends Table {
+  TextColumn get id => text()();
+  TextColumn get title => text()();
+  BoolColumn get isSynced => boolean().withDefault(const Constant(false))();
+  BoolColumn get isDeleted => boolean().withDefault(const Constant(false))();
+  @override Set<Column> get primaryKey => {id};
+}
+
+// Watch (reactive, like observeAll)
+Stream<List<Post>> watchAllPosts() => (select(posts)
+  ..where((p) => p.isDeleted.equals(false))
+  ..orderBy([(p) => Ordering.desc(p.createdAt)]))
+  .watch();
+
+// Soft delete
+Future<void> softDeletePost(String id) => (update(posts)).write(
+  PostsCompanion(id: Value(id), isDeleted: const Value(true), isSynced: const Value(false)),
+);
+```
+
+```dart
+// Sync: check connectivity first
+Future<void> sync() async {
+  final result = await Connectivity().checkConnectivity();
+  if (result == ConnectivityResult.none) return;
+  await _pushChanges();
+  await _pullChanges();
+}
+
+// Background sync on connectivity restore
+Connectivity().onConnectivityChanged.listen((result) {
+  if (result != ConnectivityResult.none) sync();
+});
+```
+
+---
+
+## iOS — SwiftData (iOS 17+) / Core Data
+
+```swift
+@Model final class Post {
+    @Attribute(.unique) var id: String
+    var title: String
+    var isSynced: Bool = false
+    var isDeleted: Bool = false
+    var updatedAt: Date?
+}
+
+// Sync with NWPathMonitor
+private func startNetworkMonitoring() {
+    monitor.pathUpdateHandler = { [weak self] path in
+        Task { @MainActor in
+            if path.status == .satisfied { await self?.sync() }
+        }
+    }
+    monitor.start(queue: queue)
+}
+
+func sync() async {
+    guard isConnected else { return }
+    let unsynced = try await repository.fetchUnsynced()
+    for post in unsynced {
+        post.isDeleted
+            ? try await apiClient.deletePost(post.id)
+            : try await apiClient.upsertPost(post)
+        post.isSynced = true
+    }
+    let remote = try await apiClient.fetchPosts()
+    for post in remote { try await repository.upsert(post) }
+}
+```
+
+---
+
+## Android — Room + WorkManager
+
+```kotlin
+@Entity(tableName = "posts")
+data class PostEntity(
+    @PrimaryKey val id: String,
+    val title: String,
+    val isSynced: Boolean = false,
+    val isDeleted: Boolean = false,
+    val updatedAt: Long? = null,
+)
+
+@Dao interface PostDao {
+    @Query("SELECT * FROM posts WHERE isDeleted = 0 ORDER BY createdAt DESC")
+    fun observeAll(): Flow<List<PostEntity>>
+
+    @Query("SELECT * FROM posts WHERE isSynced = 0")
+    suspend fun getUnsynced(): List<PostEntity>
+
+    @Query("UPDATE posts SET isDeleted = 1, isSynced = 0 WHERE id = :id")
+    suspend fun softDelete(id: String)
+}
+
+// Use WorkManager for background sync (respects battery/network constraints)
+fun triggerSync() {
+    val request = OneTimeWorkRequestBuilder<SyncWorker>()
+        .setConstraints(Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build())
+        .build()
+    WorkManager.getInstance(context).enqueue(request)
+}
+```
+
+---
+
+## Conflict Resolution
+
+```typescript
+// 1. Last Write Wins (simple, most apps)
+const resolve = (local: Post, remote: Post) =>
+  local.updatedAt > remote.updatedAt ? local : remote;
+
+// 2. Field-Level Merge (collaborative editing)
+const merge = (local: Post, remote: Post, base: Post) => ({
+  ...base,
+  title: local.title !== base.title ? local.title : remote.title,
+  body: local.body !== base.body ? local.body : remote.body,
+  updatedAt: Date.now(),
+});
+
+// 3. Operational Transform (counters/accumulators)
+const resolveCounter = (local: Counter, remote: Counter, base: Counter) => ({
+  ...remote,
+  value: base.value + (local.value - base.value) + (remote.value - base.value),
+});
+```
+
+---
+
+## UI Components
+
+```typescript
+// Offline banner
+export function OfflineBanner() {
+  const [isOffline, setIsOffline] = useState(false);
+  useEffect(() => NetInfo.addEventListener(s => setIsOffline(!s.isConnected)), []);
+  if (!isOffline) return null;
+  return <Banner message="Offline — changes sync when connected." />;
+}
+
+// Sync status
+type SyncStatus = 'synced' | 'pending' | 'syncing' | 'error';
+const STATUS_CONFIG = {
+  synced:  { icon: 'check-circle', color: 'green' },
+  pending: { icon: 'clock',        color: 'orange' },
+  syncing: { icon: 'sync',         color: 'blue' },
+  error:   { icon: 'alert-circle', color: 'red' },
+};
+
+// Optimistic update with rollback
+const updateOptimistic = async (id: string, updates: Partial<Post>) => {
+  const prev = queryClient.getQueryData(['posts', id]);
+  queryClient.setQueryData(['posts', id], old => ({ ...old, ...updates }));
+  try {
+    await repository.update(id, updates);
+    await syncDatabase();
+  } catch {
+    queryClient.setQueryData(['posts', id], prev);
+  }
+};
+```
+
+---
+
+## Database Selection
+
+| DB | Platform | Use when |
+|----|----------|----------|
+| **WatermelonDB** | React Native | Complex queries, observables, built-in sync |
+| **MMKV** | React Native | Key-value only, speed critical |
+| **Realm** | RN / Flutter / iOS | Cross-platform, reactive |
+| **SQLite** | All | Full SQL control |
+| **Drift** | Flutter | Type-safe, migrations, code gen |
+| **SwiftData** | iOS 17+ | Simple models, native |
+| **Core Data** | iOS | Complex relationships, migrations |
+| **Room** | Android | Flow/LiveData integration |
+
+---
+
+## Checklist
+
+```
+Data:
+□ All data written to local DB first
+□ Soft deletes (never hard delete)
+□ isSynced flag per record
+□ Conflict resolution strategy defined
+□ Retry for failed syncs
+
+UI:
+□ Offline banner
+□ Sync status indicator
+□ Optimistic updates
+□ Pull-to-refresh triggers sync
+
+Sync:
+□ Sync on app foreground
+□ Sync on connectivity restore
+□ Background sync (30s interval)
+□ Sync doesn't block UI thread
+```
+
+---
+
+## Anti-Patterns
+
+```
+❌ UI reads directly from API
+❌ Blocking UI during sync
+❌ Hard deletes (breaks sync)
+❌ Syncing on every keystroke
+❌ No retry for failed syncs
+❌ No offline indicator
+❌ Assuming network is available
+❌ Losing data on conflict
+```

package/shared/performance-prediction.md

@@ -0,0 +1,210 @@
+# Performance Prediction — Simulate Before Deploy
+
+> Calculate frame rates, bridge calls, and memory before deploying code.
+
+## Performance Prophet Pattern
+
+**Predict behavior BEFORE deployment** using mathematical models.
+
+### Frame Budget Calculation
+
+```
+TARGET: 60 FPS = 16.67ms per frame
+PROMOTION: 120 FPS = 8.33ms per frame
+
+BUDGET BREAKDOWN (React Native):
+- JavaScript execution: 8ms
+- Bridge calls: 3ms
+- Native rendering: 4ms
+- Layout: 1.67ms
+
+RULE: Total < 16.67ms for 60 FPS
+```
+
+### Predict List Performance
+
+```typescript
+// Given code:
+<FlatList
+  data={items}  // 50 items
+  renderItem={({ item }) => (
+    <Item
+      title={item.title}  // 1 bridge call
+      image={item.image}  // 1 bridge call
+      onPress={() => logEvent(item.id)}  // 1 bridge call
+    />
+  )}
+/>
+
+// Calculate:
+Bridge calls per item: 3
+Total items: 50
+Total bridge calls: 50 × 3 = 150 calls
+Time per call: ~0.3ms
+Total time: 150 × 0.3ms = 45ms per frame
+
+// Prediction:
+16.67ms (60 FPS budget) vs 45ms (actual)
+Result: 16.67 / 45 = 0.37 → 37% of 60 FPS = 22 FPS
+Verdict: ❌ JANK - Users will notice lag
+
+// Auto-fix suggestions:
+1. Use getItemLayout (saves layout calculations)
+2. Memoize renderItem component
+3. Defer logEvent to InteractionManager
+4. Use native driver for animations
+5. Implement virtualization (windowSize: 5)
+
+Expected after fix: ~12ms per frame → 60 FPS ✓
+```
+
+### Predict Memory Usage
+
+```
+IMAGE CALCULATION:
+- Image: 1000×1000 pixels
+- Color depth: 4 bytes (RGBA)
+- Memory: 1000 × 1000 × 4 = 4MB per image
+
+List with 50 images:
+- No optimization: 50 × 4MB = 200MB
+- With thumbnail (200×200): 50 × 0.16MB = 8MB
+- Verdict: Use thumbnails + lazy load
+
+MEMORY BUDGET:
+- iOS: ~120MB baseline
+- Android: ~80MB baseline (varies by device)
+- Target: < 150MB total for stability
+```
+
+### Predict Bundle Impact
+
+```
+NEW PACKAGE: moment.js
+Size: 230KB minified
+Bundle before: 2.1MB
+Bundle after: 2.33MB
+Impact: +11% bundle size
+
+Alternatives:
+- date-fns/esm: 50KB (modular)
+- day.js: 2KB (minimal)
+Recommendation: Use day.js → 98% size reduction
+```
+
+## Quick Calculations
+
+### 1. FlatList Frame Rate
+```
+Formula: FPS = 16.67ms / (bridge_calls × 0.3ms + render_time)
+
+Example:
+- 100 items
+- 5 bridge calls per item
+- 2ms render time per item
+
+Time per frame: (100 × 5 × 0.3ms) + (100 × 2ms) = 150ms + 200ms = 350ms
+FPS: 16.67 / 350 = 0.048 → 4.8 FPS
+
+Verdict: ❌ UNUSABLE - Must optimize
+```
+
+### 2. Animation Smoothness
+```
+Rule: Use native driver when possible
+
+With native driver:
+- Runs at 60 FPS (or 120 FPS ProMotion)
+- No bridge calls per frame
+- Smooth animations
+
+Without native driver:
+- JavaScript thread: ~16.67ms budget
+- Each frame: ~2-3 bridge calls
+- Often drops to 30-45 FPS
+
+Verdict: Always use { useNativeDriver: true }
+```
+
+### 3. Network Overhead
+```
+API Response: 500KB JSON
+Parse time: ~50ms (varies by device)
+UI block: 50ms = 3 frames dropped
+
+Optimization:
+- Paginate: 50KB per page → 5ms parse
+- Background thread: 0 frames dropped
+```
+
+## Platform-Specific Predictions
+
+### React Native
+```
+KNOWN BOTTLENECKS:
+1. Bridge calls: 0.3ms each
+2. console.log: 10-50ms (dev mode)
+3. Inline styles: Re-creates every render
+4. Anonymous functions in render: Creates new reference
+
+OPTIMIZATION PRIORITY:
+1. Remove console.log (50ms → 0ms)
+2. StyleSheet.create (5ms → 0.1ms)
+3. useCallback/useMemo (prevents re-renders)
+4. Native driver animations (60 FPS guaranteed)
+```
+
+### Flutter
+```
+KNOWN BOTTLENECKS:
+1. Build method: Should be < 8ms
+2. setState: Triggers full rebuild
+3. Large widget trees: O(n) complexity
+
+OPTIMIZATION PRIORITY:
+1. const constructors (immutable widgets)
+2. ListView.builder vs ListView (O(visible) vs O(n))
+3. RepaintBoundary (isolate repaints)
+4. Selective rebuilds (Consumer vs rebuild all)
+```
+
+## Prediction Workflow
+
+```
+BEFORE IMPLEMENTING:
+1. Estimate bridge calls (RN) or build time (Flutter)
+2. Calculate frame budget impact
+3. Predict FPS: 16.67ms / total_time
+4. If < 60 FPS: redesign or optimize first
+
+AFTER IMPLEMENTING:
+1. Profile with React DevTools / Flutter DevTools
+2. Compare predicted vs actual
+3. Adjust model if off by > 20%
+4. Document learnings for next time
+```
+
+## Auto-Suggestions
+
+```
+If prediction shows < 60 FPS:
+
+FOR LISTS:
+✓ Use getItemLayout
+✓ Memoize renderItem
+✓ Reduce bridge calls
+✓ Virtualization (windowSize)
+✓ Thumbnail images
+
+FOR ANIMATIONS:
+✓ Use native driver
+✓ Avoid layout animations
+✓ Prefer transform/opacity
+✓ Use InteractionManager
+
+FOR MEMORY:
+✓ Image optimization
+✓ Lazy loading
+✓ Pagination
+✓ Clear caches
+```