Client (PWA)

Audience: Frontend engineers working on packages/client. Related docs: Monorepo Structure, packages/client/README.md Networks: Arbitrum One (42161), Celo (42220), Base Sepolia (84532). Deployment data: packages/contracts/deployments/*.json. Updated November 2024. External references: Offline data patterns mirror the TanStack Query offline guide; review it when adjusting persistence.

Offline-first Progressive Web App for gardeners to document regenerative work.

---

Quick Reference

Path: packages/client/ Port: https://localhost:3001 (HTTPS via mkcert) Stack: React 18 + TypeScript + Vite

Commands:

bun --filter client dev      # Start dev server
bun --filter client test     # Run tests
bun --filter client build    # Production build

---

Tech Stack

Core

• React 18 (lazy loading)

• TypeScript (strict mode)

• Vite (bundler)

• React Router

State Management

• TanStack Query (server state)

• Zustand (UI state)

• React Hook Form (forms)

UI

• Tailwind CSS v4

• Radix UI primitives

• CSS variables theme

Web3

• Viem (Ethereum)

• Pimlico (smart accounts)

• Reown AppKit (wallet connect)

• EAS SDK (attestations)

Storage

• IndexedDB (offline queue)

• Service Worker (PWA)

• IPFS (via Pinata)

---

Key Features

Offline-First

Job Queue System:

• Queues work when offline

• Auto-syncs when online

• Event-driven updates

• Exponential backoff retry

Implementation:

• src/modules/job-queue/

• src/providers/jobQueue.tsx

Dual Authentication

Passkey Mode (gardeners):

• WebAuthn biometric

• Kernel smart accounts

• Pimlico gasless transactions

Wallet Mode (operators):

• MetaMask, WalletConnect

• Traditional EOA

• Direct transactions

Implementation:

• src/providers/auth.tsx

• src/modules/auth/passkey.ts

MDR Workflow

Media → Details → Review:

• Camera integration

• Form validation

• Preview before submit

• IPFS upload

Implementation:

• src/views/Garden/index.tsx

• src/components/Garden/

---

Architecture Highlights

Offline Job Queue

// Submission flow
submitWork() 
  → addJob(IndexedDB)
  → processJob (if online)
  → uploadIPFS()
  → createAttestation()
  → transaction sent

Provider Hierarchy

<WagmiProvider>
  <AppProvider>
    <AuthProvider>
      <QueryClientProvider>
        <JobQueueProvider>
          <WorkProvider>
            <Routes />

Order matters: Each depends on ancestors.

---

Performance

Bundle Size:

• Main: ~4.4 MB (offline-first = larger)

• Lazy chunks: 0.3-66 KB

Optimization:

• Dynamic imports for views

• Image compression

• Code splitting

• Service worker caching

---

Complete Documentation

📖 Full details: packages/client/README.md

Key Files:

• Architecture: .cursor/rules/offline-architecture.mdc

• Auth patterns: .cursor/rules/authentication.mdc

• State management: .cursor/rules/state-management.mdc

• Component patterns: .cursor/rules/component-patterns.mdc