PWA & Offline Mode

ProBeya supports Progressive Web App (PWA) installation and offline-first workflows. Team leaders on the shop floor can view cached boards and make changes without internet connectivity, with automatic synchronization when the connection is restored.

Overview

Manufacturing environments often have unreliable network connectivity — shop floors, cleanrooms, and remote sites may have dead zones. ProBeya's offline capability ensures:

• PWA installation: Install ProBeya on any device for a native app experience
• Offline board viewing: Access cached board data without connectivity
• Offline editing: Make changes to items, add comments, and update statuses offline
• Automatic sync: Changes queue locally and sync automatically when online
• Conflict resolution: Last-write-wins strategy with CRDT-based merge for collaborative fields

Getting Started

Installing the PWA

1. Open ProBeya in Chrome, Edge, or Safari.
2. Click the install prompt in the address bar (or use the browser menu > "Install app").
3. ProBeya opens in a standalone window without browser chrome.
4. The app icon appears on your home screen or desktop.

Working Offline

1. Open a board while connected — the data is automatically cached.
2. Disconnect from the network (or walk to a dead zone).
3. Continue viewing and editing the board normally.
4. A banner indicates you are working offline.
5. When connectivity returns, changes sync automatically.

How It Works

Service Worker

The PWA uses a service worker (via next-pwa) to cache:

• App shell: HTML, CSS, JavaScript bundles for instant loading
• API responses: Board data, KPI values, and item lists for offline access
• Static assets: Icons, fonts, and images
• Translation files: All six locale message bundles (EN, FR, NL, DE, IT, ES) for internationalized offline access

Cache Strategies

ProBeya uses different caching strategies depending on the resource type:

Resource Type	Strategy	Rationale
App shell (HTML/CSS/JS)	Cache-first, network fallback	Ensures instant loading; updates on next visit
API responses (board data)	Network-first, cache fallback	Always shows latest data when online; falls back to cached data offline
Static assets (icons, fonts)	Cache-first, long TTL	Rarely changes; maximize performance
Translation bundles	Cache-first, background update	Ensures i18n works offline; updates silently

Offline Queue

When the user makes changes while offline:

1. The change is applied optimistically to the local UI state (Zustand store)
2. The mutation is serialized and queued in IndexedDB
3. A sync indicator shows the pending changes count
4. When connectivity returns, queued mutations replay in order via the tRPC client
5. Conflicts are resolved using last-write-wins with timestamps
6. Failed mutations are retried with exponential backoff

The queue persists across browser restarts, so closing the PWA while offline does not lose pending changes.

Offline-Capable Operations

The following operations are supported while offline:

Operation	Offline Support
View cached boards	Full
Update item values	Full (queued)
Change item status	Full (queued)
Add comments	Full (queued)
Submit mood entries	Full (queued)
View KPI charts	Cached data only
Create new items	Full (queued with temporary IDs)
Upload files	Not supported (requires network)
Real-time collaboration (Yjs)	Reconnects automatically when online

Web App Manifest

The manifest.json provides:

• App name, short name, and description
• Theme color matching the organization's branding (falls back to default ProBeya blue)
• Icons at multiple resolutions (192x192, 512x512)
• display: standalone for native-like experience
• start_url pointing to /dashboard
• orientation: any for both portrait and landscape support

Background Sync

When the browser supports the Background Sync API, ProBeya registers a sync event that fires when connectivity is restored, even if the PWA is not in the foreground. This ensures queued mutations are processed as soon as possible without requiring the user to manually open the app.

Conflict Resolution Strategy

ProBeya uses a last-write-wins strategy for offline conflict resolution:

• Each change carries a timestamp from the client
• During sync, the server compares timestamps
• The most recent write wins for scalar fields (status, single-value cells)
• For collaborative text fields (long text, comments), CRDT-based merging via Yjs preserves concurrent edits

This approach was chosen over full CRDT for all fields because:

• Most operations in manufacturing contexts are single-user updates (e.g., status changes on the shop floor)
• Last-write-wins is simpler to reason about and debug
• CRDT overhead is only justified for truly collaborative fields
• The Yjs integration in apps/ws/ handles the CRDT complexity for long-text fields

See ADR-016: Offline/PWA Strategy for the full decision record.

Sync Status Indicators

The UI provides clear feedback about sync state:

Indicator	Meaning
Green check	All changes synced successfully
Orange badge with count	N changes pending sync
Red warning	Sync failed, will retry automatically
Gray cloud with slash	Currently offline

Performance Optimizations

• Selective caching: Only boards the user has visited are cached, preventing unnecessary storage usage
• Cache eviction: Least-recently-used boards are evicted when storage exceeds the browser's quota
• Incremental updates: After reconnecting, only changed data is fetched rather than full board refreshes
• Compressed payloads: API responses are gzip-compressed to minimize cache storage

Related Features

• Mobile-friendly responsive layouts optimized for phone and tablet
• TIER Meeting — Run daily standups with offline-cached data
• Mood Tracking — Submit mood entries offline during shop floor rounds