Qortal-Nextcloud-Integration/docs/pwa-phase1-phase2-release-plan.md

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)