Architecture Overview
WEFA is a local-first PWA that can run fully offline and progressively "upgrades" into shared play, social distribution, and verifiable outcomes as users opt in.
System Architecture
Layered Architecture
1. Realtime Session Layer
Low-latency match state + AR scene state for active players. Uses Yjs with small documents — sync moves and anchor transforms, not per-frame physics.
2. Proof Layer
Portable, verifiable claims about what happened. EAS offchain attestations signed by player wallet/smart-account. Optional onchain timestamping at milestones.
3. Social / Discovery Layer
AT Protocol for account portability, proof references, and social distribution. Users can sign in with AT (Bluesky) and link EVM later.
4. Access / Membership Layer
Unlock Protocol locks/keys for tournaments, shrine events, and seasonal campaigns. Fail-open behavior for offline and non-gated play.
Design Principles
- Local-first: Dexie/IndexedDB is the source of truth. Network features are additive.
- Progressive decentralization: Start offchain, optionally anchor onchain, evolve toward autonomous world.
- Youth-safe defaults: Never leak location, faces, or plant photos publicly by default.
- Replaceable infra: Any relay/indexer/backend is plumbing, not a hard dependency.
- Ship-first: Base + Base Sepolia chains. Avoid custom servers unless they unlock core loop or safety.
Key Technology Decisions
| Decision | Choice | Rationale |
|---|---|---|
| Local DB | Dexie 4 | Wrapper over IndexedDB with better queries and error handling |
| Runtime ECS | bitECS | Typed arrays for fast entity management, no strings/objects |
| State machines | XState 5 | Explicit, testable flows; setup() API |
| P2P sync | Yjs + y-webrtc | CRDTs merge without conflicts; offline persistence via y-indexeddb |
| Proofs | EAS SDK 2 | Offchain-first attestations; portable and verifiable |
| Auth | Passkey (Pimlico) + Wallet (Reown) | Dual-mode for accessibility |
| 3D / AR | R3F + @react-three/xr v6 | React mental model for 3D; native click API (no <Interactive>) |
| Styling | Layered CSS tokens/primitives + Radix UI | Repo-local design tokens + accessible primitives |