Skip to main content

Offline-First Architecture

WEFA's core loop works entirely without network. This is a hard requirement, not a nice-to-have.

What Works Offline​

  • Login (session restoration from localStorage)
  • Full onboarding (seed pack fallback for creature generation)
  • Add plant + daily care
  • Creature nurture and evolution
  • Pass-and-play games (Device mode)
  • View deck, collection, stats
  • PWA shell rendering

What Requires Network​

  • Creature generation via Claude API + Meshy (falls back to seed pack)
  • Local/World multiplayer (Yjs sync)
  • EAS attestation creation (queued for later)
  • AT Protocol publishing (queued for later)
  • Plant identification via Plant.ID

Persistence Strategy​

DataStorageSync
Player profileDexie (IndexedDB)None (local-only in V1)
Plants + care eventsDexieJob queue -> EAS when online
Creatures + assetsDexie + blob cacheNone
Game sessions/resultsDexieJob queue -> EAS when online
Auth sessionlocalStorageNone
Yjs game docsy-indexeddbResume interrupted sessions
AttestationsDexieOptional onchain timestamp

Service Worker​

Configured via vite-plugin-pwa with Workbox:

  • Precache: App shell, seed pack sprites, icons
  • Runtime cache:
    • CacheFirst for creature templates
    • StaleWhileRevalidate for generated creature assets
    • NetworkFirst for API calls

PWA Configuration​

  • display: standalone (installable)
  • Theme color: earth green
  • Manifest icons: 192px and 512px
  • Service worker registration in src/main.tsx
  • Update prompt when new version available

iOS Safari Considerations​

  • IndexedDB quota: ~50MB per origin
  • Monitor usage with cache management in src/modules/creature-generator/cache.ts
  • Evict old creature assets when approaching limit
  • Font minimum 16px on inputs (prevents zoom)
  • Safe area insets: env(safe-area-inset-*)

Background Sync​

When the device comes back online, the Background Sync API triggers a flush of the job queue, processing any pending attestation or reporting jobs.

Key Files​

  • vite.config.ts - PWA and Workbox configuration
  • src/main.tsx - Service worker registration
  • src/modules/creature-generator/cache.ts - Asset cache with quota management
  • src/modules/job-queue/ - Background job queue
  • public/manifest.json - PWA manifest