# PWA Release Concept (Phase 1 -> Phase 2)

## Goal
Ship a strong mobile-ready release quickly without splitting into separate app codebases too early.

## Phase 1: strongest possible web push path

### Core deliverables
- Installable manifest with stable identity:
  - `id`, `name`, `short_name`, `start_url`, `scope`, `display: standalone`
  - maskable icons
  - shortcuts to core actions
- Service worker versioning and controlled lifecycle:
  - version token tied to theming/cachebuster
  - `install`, `activate`, `push`, `notificationclick`
- Notification readiness flow:
  - explicit onboarding/readiness screen
  - notification permission state
  - service worker registration state
  - push subscription state
- Notification UX/ops controls:
  - `Test notification` button
  - `Last successful push received at` status
  - subscription refresh/re-register action

### Delivery behavior
- Deep links should target exact app/resource URLs.
- Use notification actions where practical in service worker payload handling.
- Keep fallback email for important notifications.
- Keep optional SMS for critical-only events (later connector/backend expansion).

### Health + telemetry expectations
- Track per-device registration state in backend.
- Record subscription freshness and stale endpoints.
- Expose in-app health checks before users rely on Talk alerts.

## Phase 2: wrap, do not rewrite

When web reliability becomes the limiting factor:
- Wrap existing web app with Capacitor first.
- Defer React Native/full native split unless native-heavy features become mandatory.

### Why this path
- Faster route to APNs/FCM native push channels.
- Better background behavior and app-store presence.
- Lower risk than parallel app rewrites.

## Current implementation baseline

Implemented now in `custom_pwa`:
- Expanded install page into readiness center:
  - install prompt state
  - standalone state
  - notification permission state
  - service worker registration state
  - push subscription state
  - last notification timestamp
- Added test notification action.
- Added service worker refresh/re-register action.
- Added service worker endpoint with versioned script.
- Added manifest enrichments (description, display override, shortcuts).
- Added backend per-device status scaffolding:
  - device registration API
  - device status API
  - push-received timestamp API
  - test-notification backend status API
  - VAPID-backed browser push delivery test
  - stale endpoint marking for failed push delivery

## Next immediate tasks

1. Add deeper push delivery result reporting for operational dashboards.
2. Add readiness deep-link checks for Talk preflight path.
3. Add optional email fallback adapter trigger for critical notification classes.

## Current config keys (custom_pwa app values)

- `vapid_subject` (example: `mailto:alerts@your-domain.tld`)
- `vapid_public_key` (base64url VAPID public key)
- `vapid_private_key` (PEM EC private key or base64url 32-byte private key)