Skip to content

PWA Architecture - Farmer App

Purpose

This document defines the architectural approach for the Farmer1st mobile application, built as a Progressive Web Application targeting farmers worldwide, including those with older devices and unreliable connectivity.

Current State

Application Type

  • Progressive Web Application (PWA)
  • Framework: React
  • Target: Mobile-first, responsive

Target Environment

┌─────────────────────────────────────────────────────────────┐
│                    DEVICE SPECTRUM                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  LOW-END (Primary Target)    MID-RANGE        HIGH-END     │
│  ┌─────────────────────┐    ┌──────────┐    ┌──────────┐  │
│  │ • 1-2GB RAM         │    │ • 3-4GB  │    │ • 6GB+   │  │
│  │ • Android 5.0-8.0   │    │ • Android│    │ • Latest │  │
│  │ • 2G/3G connection  │    │   9-11   │    │ • 4G/5G  │  │
│  │ • Limited storage   │    │ • 4G     │    │ • Fast   │  │
│  │ • Older processors  │    │          │    │          │  │
│  └─────────────────────┘    └──────────┘    └──────────┘  │
│         ▲                                                   │
│         │                                                   │
│    MUST WORK HERE                                          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Decisions and Rationale

Why PWA Over Native

Factor PWA Advantage Native Trade-off
Distribution Direct URL access, no store needed Easier discovery in app stores
Updates Instant, automatic Requires user action
Storage No installation quota on device Guaranteed storage allocation
Development Single codebase Better platform integration
Offline Service workers enable offline More robust offline APIs
Device Access Limited but improving Full hardware access

Decision: PWA benefits outweigh trade-offs for our farmer demographic.

Core PWA Requirements

  1. Installable: Add to home screen capability
  2. Offline-capable: Core features work without network
  3. Fast: Loads quickly on slow connections
  4. Responsive: Works on any screen size
  5. Safe: Served over HTTPS

Architectural Principles

1. Offline-First Design

┌────────────────────────────────────────────────────────┐
│                  OFFLINE-FIRST PATTERN                 │
├────────────────────────────────────────────────────────┤
│                                                        │
│   User Action                                          │
│       │                                                │
│       ▼                                                │
│   ┌───────────────┐                                   │
│   │ Local Storage │ ◄─── Always write here first      │
│   │  (IndexedDB)  │                                   │
│   └───────┬───────┘                                   │
│           │                                            │
│           ▼                                            │
│   ┌───────────────┐     ┌─────────────────┐          │
│   │  Sync Queue   │────►│  Backend API    │          │
│   │               │     │  (when online)  │          │
│   └───────────────┘     └─────────────────┘          │
│                                                        │
└────────────────────────────────────────────────────────┘

2. Performance Budget

Metric Target Rationale
Initial JS Bundle < 200KB gzipped Low-end device parsing
Total Initial Load < 500KB 3G bandwidth constraints
Time to Interactive < 3s on 3G User patience threshold
Memory Usage < 150MB 1GB RAM devices
Lighthouse Score > 90 PWA best practices

3. Progressive Enhancement

  • Core functionality works on oldest supported browsers
  • Enhanced features for modern browsers
  • Graceful degradation when features unavailable

Technical Considerations

Service Worker Strategy

  • Caching: Cache-first for static assets, network-first for API
  • Background Sync: Queue actions when offline, sync when online
  • Update Strategy: TBD (prompt user vs silent update)

Data Storage

  • IndexedDB: Primary offline data storage
  • LocalStorage: Small config/preference data
  • Cache API: Static assets and API responses

Bundle Optimization

  • Code splitting by route
  • Lazy loading of non-critical features
  • Tree shaking for minimal bundle
  • Image optimization (WebP with fallbacks)

Constraints

Hard Constraints

  1. Must work on Android 5.0+ (API level 21)
  2. Must function with 1GB RAM
  3. Must work on 2G/3G networks
  4. Must support offline core workflows

Soft Constraints

  1. iOS PWA limitations accepted (no push notifications, limited background sync)
  2. Some native features unavailable (NFC, Bluetooth, advanced sensors)

Open Questions

  • Which offline-first library to use? (e.g., Workbox, custom)
  • State management approach for offline sync?
  • What are the "core workflows" that must work offline?
  • Authentication flow for offline-first?
  • How to handle data conflicts during sync?
  • Image/media handling strategy for low bandwidth?

Dependencies

  • React ecosystem decisions (see 01-technology-stack.md)
  • Backend API design (affects sync patterns)
  • Authentication strategy (affects offline access)

Last Updated: 2025-12-25