Data Layer

WEFA uses a three-tier data architecture: Dexie for persistence, bitECS for runtime entity management, and Zod for validation at all boundaries.

Dexie (IndexedDB)

The WEFADatabase is the local-first source of truth with these tables:

Table	Purpose
players	Player profiles, element, biome, energy
plants	Plant inventory with photos, species, health
careEvents	Daily care event log
creatures	Creature collection with stats, stage, traits
nurtureEvents	Creature nurture event log
gameSessions	Active and completed game sessions
gameResults	Match outcomes and rewards
badges	Earned achievement badges
attestations	EAS attestation records
eventLog	General event audit trail
creatureAssets	Blob cache for sprites and GLB models

Reactive Queries

Use useLiveQuery from Dexie for reactive local data, not TanStack Query:

// Correct: reactive to local changes
const plants = useLiveQuery(() => db.plants.toArray());

// TanStack Query is for network requests with Dexie persistence
const { data } = useQuery({
  queryKey: ['api-data'],
  networkMode: 'offlineFirst',
});

bitECS (Runtime)

bitECS manages fast entity queries during gameplay using typed arrays (numbers only, no strings or objects).

Components

// Components use typed arrays
const Element = defineComponent({ value: Types.ui8 });
const Health = defineComponent({ current: Types.ui16, max: Types.ui16 });
const Energy = defineComponent({ value: Types.ui32 });
const Stage = defineComponent({ value: Types.ui8 });
const Stats = defineComponent({
  health: Types.ui16,
  power: Types.ui16,
  defense: Types.ui16,
  speed: Types.ui16,
});

Sync with Dexie

Entities sync between Dexie (persistence) and bitECS (runtime) via utility functions:

• loadFromDexie() - Hydrate bitECS world from Dexie on startup
• syncToDexie() - Persist bitECS state back to Dexie
• A Map<string, number> maps Dexie IDs to bitECS entity IDs

Zod (Validation)

All data boundaries use Zod schemas defined in src/types/:

• player.ts - PlayerSchema
• plant.ts - PlantSchema, CareEventSchema
• creature.ts - CreatureSchema, NurtureEventSchema
• game.ts - GameSessionSchema, GameResultSchema
• common.ts - Element, Biome, Badge, CreatureStage enums

Each schema exports both the Zod schema and inferred TypeScript type.

Key Files

• src/modules/db.ts - Dexie database definition
• src/modules/ecs.ts - bitECS world, components, systems
• src/types/ - All Zod schemas and TypeScript types