deardiary/todo/mobile.md

DearDiary Mobile & PWA Support Research

Current state: DearDiary already has a basic manifest.json (standalone display, icons) but no service worker or offline support.

---

1. PWA Foundation (Service Worker + Manifest)

Feature: Full PWA Implementation with Offline Support

Description: Enable DearDiary to be installable on mobile devices and work offline with full caching strategy.

Technical Requirements:

• Add vite-plugin-pwa to vite.config.ts
• Configure workbox strategies (cache-first for assets, network-first for API)
• Service worker with precaching for app shell
• Enhanced manifest with categories, orientation, launch_handler

Implementation Steps:

1. Install vite-plugin-pwa and workbox-window
2. Update vite.config.ts with PWA plugin configuration
3. Extend manifest.json with categories, screenshots, maskable icons
4. Create custom service worker for API caching strategies

Complexity: Medium (3-5 hours) Priority: HIGH - Foundation for all mobile features

PWA Plugin Config Example:

import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig({
  plugins: [
    VitePWA({
      registerType: 'autoUpdate',
      includeAssets: ['icon-192.png', 'icon-512.png'],
      manifest: {
        categories: ['productivity', 'lifestyle'],
        orientation: 'portrait',
      },
      workbox: {
        globPatterns: ['**/*.{js,css,html,png,svg}'],
        runtimeCaching: [{
          urlPattern: /^https:\/\/api\//,
          handler: 'NetworkFirst',
          options: {
            cacheName: 'api-cache',
            expiration: { maxEntries: 50, maxAgeSeconds: 86400 }
          }
        }]
      }
    })
  ]
})

---

2. Offline-First Architecture

Feature: IndexedDB Local Storage with Background Sync

Description: Store events locally when offline, sync to server when connection restored.

Technical Requirements:

• IndexedDB via idb library or dexie.js
• Sync queue for pending events
• Background Sync API (sync event) for automatic retry
• Conflict resolution for server/client changes

Implementation Steps:

1. Create IndexedDB schema: events, journals, syncQueue
2. Build OfflineStorage service with add/get/sync methods
3. Modify QuickAddWidget to use offline storage first
4. Implement BackgroundSync handler in service worker
5. Add sync status indicator in UI

Complexity: High (6-8 hours) Priority: HIGH - Core offline functionality

Dexie Schema Example:

import Dexie from 'dexie';

class DearDiaryDB extends Dexie {
  events!: Table<Event>;
  journals!: Table<Journal>;
  syncQueue!: Table<SyncItem>;
  
  constructor() {
    super('DearDiaryDB');
    this.version(1).stores({
      events: '++id, date, type, createdAt, synced',
      journals: 'date, syncedAt',
      syncQueue: '++id, type, data, createdAt'
    });
  }
}

Sync Flow:

1. User creates event → save to IndexedDB → add to syncQueue → show "pending sync" badge
2. Service worker registers 'sync' event → fetch all queued items → POST to API
3. On success → delete from queue → mark event as synced
4. On failure → retry on next sync or when online

---

3. Install Prompt & App-Like Experience

Feature: Custom Install Prompt with Native Feel

Description: Detect when PWA is installable, show custom prompt, improve app icon/splash.

Technical Requirements:

• beforeinstallprompt event listener
• Custom install button in UI (not browser prompt)
• Splash screen configuration via theme_color + background_color
• Maskable adaptive icons for Android

Implementation Steps:

1. Add install prompt handler in App.tsx
2. Create custom "Add to Home Screen" UI component
3. Generate adaptive icon with SVG maskable version
4. Add <meta name="apple-mobile-web-app-capable"> for iOS
5. Add iOS-specific icons (apple-touch-icon)

Complexity: Low (2-3 hours) Priority: MEDIUM

iOS Support:

<link rel="apple-touch-icon" href="/icon-192.png">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

---

4. Mobile-Responsive UI Improvements

Feature: Mobile-Optimized Layout & Touch Targets

Description: Improve mobile usability with larger touch targets, bottom navigation, responsive grid.

Technical Requirements:

• Minimum 44px touch targets
• Bottom tab bar for mobile (Dashboard, Today, History, Settings)
• Responsive padding and font sizes
• Swipe gestures for navigation

Implementation Steps:

1. Create responsive layout component with mobile nav
2. Adjust QuickAddWidget for bottom-sheet on mobile
3. Add touch-action CSS for swipe handling
4. Media queries for mobile-specific styling
5. Test on actual device or responsive mode

Complexity: Medium (4-5 hours) Priority: HIGH - User-facing

Mobile Navigation Example:

// BottomNav.tsx
<nav className="fixed bottom-0 left-0 right-0 bg-slate-900 border-t border-slate-800 flex justify-around py-3">
  <NavLink to="/" icon={Home} />
  <NavLink to="/today" icon={PlusCircle} />
  <NavLink to="/history" icon={Clock} />
  <NavLink to="/settings" icon={Cog} />
</nav>

---

5. Push Notifications

Feature: Event Reminder Notifications

Description: Send push notifications to remind users to log events throughout the day.

Technical Requirements:

• Web Push API (VAPID keys)
• Service worker push event handler
• Notification permission request flow
• Configurable reminder schedule in settings

Implementation Steps:

1. Generate VAPID key pair
2. Add Web Push subscription endpoint to backend
3. Create notification service in frontend
4. Add "Enable Reminders" toggle in Settings
5. Schedule notifications via service worker

Complexity: High (5-7 hours) Priority: MEDIUM

Note: Web Push requires VAPID keys and HTTPS. For iOS Safari, use APNs integration (requires native wrapper or PWABuilder).

---

6. Touch-Friendly Interactions

Feature: Gesture-Based Navigation & Input

Description: Add swipe gestures, long-press actions, haptic feedback for mobile.

Technical Requirements:

• Touch event handlers for swipe detection
• Haptic feedback API (navigator.vibrate)
• Pull-to-refresh on event lists
• Swipe-to-delete on events

Implementation Steps:

1. Add gesture detection hook (useSwipe)
2. Implement pull-to-refresh on Today page
3. Add haptic feedback on button presses
4. Implement swipe actions on event list items

Complexity: Medium (3-4 hours) Priority: MEDIUM

Implementation Pattern:

function useSwipe(onSwipeLeft: () => void, onSwipeRight: () => void) {
  const touchStart = useRef({ x: 0, y: 0 });
  
  const onTouchStart = (e: TouchEvent) => {
    touchStart.current = { x: e.touches[0].clientX, y: e.touches[0].clientY };
  };
  
  const onTouchEnd = (e: TouchEvent) => {
    const deltaX = e.changedTouches[0].clientX - touchStart.current.x;
    if (Math.abs(deltaX) > 50) {
      deltaX > 0 ? onSwipeRight() : onSwipeLeft();
    }
  };
  
  return { onTouchStart, onTouchEnd };
}

---

7. Offline Event Capture (Sync Later)

Feature: Queue Events When Offline, Sync When Online

Description: Full implementation of offline-first event creation.

Technical Requirements:

• IndexedDB event storage
• Visual queue indicator (X events pending)
• Force sync button
• Automatic sync on reconnection

Implementation Steps:

1. Build offline event queue system (see section 2)
2. Add sync status banner to Today page
3. Add manual "Sync Now" button
4. Show toast on successful sync
5. Handle partial sync failures gracefully

Complexity: High (already covered in section 2) Priority: HIGH

---

8. Background Sync for API Calls

Feature: Automatic Background Synchronization

Description: Use Background Sync API to automatically sync pending operations when online.

Technical Requirements:

• Service worker sync event handler
• Tag pending requests with sync ID
• Retry with exponential backoff
• Notify user of sync completion

Implementation Steps:

1. Register background sync in service worker
2. Trigger sync when events are added offline
3. Implement retry logic with backoff
4. Send desktop notification on sync complete

Complexity: Medium (3-4 hours) Priority: MEDIUM

---

Implementation Roadmap

Phase 1: Foundation (HIGH)

• PWA manifest & service worker setup
• Basic offline caching for app shell
• IndexedDB local storage

Phase 2: Offline Sync (HIGH)

• Offline event capture
• Background sync
• Sync status UI

Phase 3: Mobile UX (MEDIUM)

• Responsive layout with bottom nav
• Touch-friendly interactions
• Install prompt

Phase 4: Advanced (LOW)

• Push notifications
• Advanced gestures
• iOS PWA optimization

---

Summary

Feature	Complexity	Priority
PWA Setup + Service Worker	Medium	HIGH
IndexedDB + Offline Storage	High	HIGH
Mobile UI + Bottom Nav	Medium	HIGH
Install Prompt	Low	MEDIUM
Background Sync	Medium	MEDIUM
Push Notifications	High	MEDIUM
Touch Gestures	Medium	MEDIUM

Recommended First Steps:

1. Add vite-plugin-pwa and configure basic caching
2. Implement IndexedDB with Dexie for event storage
3. Build offline-first QuickAddWidget
4. Add sync queue UI indicator