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

Data	Storage	Sync
Player profile	Dexie (IndexedDB)	None (local-only in V1)
Plants + care events	Dexie	Job queue -> EAS when online
Creatures + asset metadata	Dexie + Cache Storage	None
Game sessions/results	Dexie	Job queue -> EAS when online
Auth session	localStorage	None
Yjs game docs	y-indexeddb	Resume interrupted sessions
Attestations	Dexie	Optional onchain timestamp

Service Worker

Configured via vite-plugin-pwa with Workbox:

• Precache: App shell, icons, seed creature thumbnails
• Runtime cache:
  • CacheFirst for creature thumbnails
  • CacheFirst for creature GLBs requested at runtime

There is no generic API runtime cache in the current service worker. App data stays local through Dexie and the job queue.

PWA Configuration

• display: standalone (installable)
• Theme color: earth green
• Manifest icons: 192px and 512px
• Service worker registration in src/main.tsx via registerSW({ immediate: true })
• Build-time precache audit keeps heavy creature assets out of dist/sw.js

iOS Safari Considerations

• Browser storage quotas vary and can be evicted under pressure
• The default install path stays small by keeping 3D creature assets out of the precache
• Optional creature 3D downloads are stored in Cache Storage, with pin metadata tracked in Dexie
• 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-assets.ts - Asset selection and offline pinning helpers
• src/modules/db.ts - Dexie tables, including pinned asset metadata
• src/modules/job-queue/ - Background job queue
• public/manifest.json - PWA manifest