> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-013: PWA Strategy with Workbox Service Worker

> Status: Accepted Date: 2026-04-12 Participants: Platform Architecture Team, Jeremy Bloom

**Status:** Accepted\
**Date:** 2026-04-12\
**Participants:** Platform Architecture Team, Jeremy Bloom

***

## Context

Encore Health OS serves behavioral health staff who work in facilities with variable internet connectivity (residential facilities, outpatient offices, sometimes mobile in the field). The platform needed to work reliably on mobile devices and in low-connectivity environments. Two options: native mobile apps per platform, or a Progressive Web App.

## Options Considered

### Option A: Native mobile apps (iOS + Android)

* **How it works:** Separate React Native or native apps for iOS and Android; web app for desktop.
* **Pros:** Full native capabilities; offline-first design; platform-specific UX patterns.
* **Cons:** Three codebases to maintain (web, iOS, Android); significant development cost; app store review delays; separate deployment pipeline; user must install from store; healthcare apps face additional App Store review scrutiny.
* **Why not chosen:** Three codebases for a complex ERP platform is prohibitively expensive. App store dependencies add operational risk.

### Option B: Progressive Web App with Workbox ✓

* **How it works:** Single codebase; Vite PWA plugin generates a service worker using Workbox; users can "install" the app to their home screen on any platform; offline caching strategies per request type.
* **Pros:** Single codebase; installable on iOS, Android, and desktop; no app store; Workbox provides fine-grained caching strategies; `vite-plugin-pwa` integrates seamlessly with Vite; auto-update strategy keeps all users on latest version.
* **Cons:** PWA limitations on iOS (some features like push notifications were historically limited, improving in iOS 17+); requires careful service worker cache management; auth tokens cannot be cached (NetworkOnly for auth).
* **Why chosen:** Single codebase is the decisive factor. Workbox strategies (CacheFirst for fonts/images/storage, NetworkFirst for REST API, NetworkOnly for auth) cover the full spectrum of caching needs. HHS WCAG 2.1 AA compliance requirement further aligns with web-first approach.

## Decision

The platform is a PWA using `vite-plugin-pwa` with Workbox. Cache strategies:

* **CacheFirst:** Static fonts, images, Supabase Storage assets (long-lived, content-addressed)
* **NetworkFirst:** Supabase REST API calls (fresh data preferred, cache as fallback)
* **NetworkOnly:** Supabase Auth endpoints (never cached; stale auth data is a security risk)

Auto-update strategy: `autoUpdate: true` — new service workers activate immediately. Manifest configured for standalone mode with appropriate icons and theme color. Mobile-first responsive design is required by constitution §6.

## Consequences

### Positive

* Single codebase for all platforms (web, mobile, desktop install)
* No app store dependency or review delays
* Workbox CacheFirst for assets dramatically reduces repeat load times
* Staff can use core features in low-connectivity environments via NetworkFirst REST caching

### Negative

* Service worker complexity (must be carefully managed to avoid stale cache bugs)
* Auto-update may cause in-progress work to be interrupted (mitigated by showing update prompts)
* iOS PWA limitations (improving but still present in some areas)

### Mitigations

* Workbox generates the service worker automatically from `vite-plugin-pwa` config
* NetworkOnly for auth prevents stale token issues
* Mobile-first design enforced by constitution §6 and UI/UX standards
* WCAG 2.1 AA compliance (HHS May 2026 deadline) addressed by web-first approach

## Related Documents

* [Constitution §6 PWA & UI](../../../constitution.md) — PWA requirements, mobile-first
* [docs/development/UI\_UX\_STANDARDS.md](../../development/UI_UX_STANDARDS.md)
* [vite.config.ts](../../../vite.config.ts) — Workbox and PWA configuration