supersam/docs/superpowers/specs/2026-03-14-pwa-demo-dashboard-design.md

PWA Demo Dashboard Design

Date: 2026-03-14

Goal: Turn the app into an installable PWA and add a dashboard panel that explains what PWA is, why it matters for demo mode, and how the offline demo behaves.

Context

• The app already has a demo mode that works without Supabase configuration.
• Demo login state is stored locally in localStorage.
• Demo orders, notifications, and users are already shipped with the frontend bundle.
• Git history shows an earlier public/service-worker.js, but the current workspace no longer contains the PWA assets.

Decision

Implement a manual PWA layer for the Vite app and pair it with a dashboard-only "Demo and PWA" panel.

This keeps the solution dependency-light, restores full control over caching behavior, and lets the demo flow work offline after the first successful load.

Architecture

PWA shell

• Add a public/ directory with:
  • manifest.webmanifest
  • service-worker.js
  • app icons for install surfaces
• Register the service worker from src/main.jsx.
• Cache the app shell with a conservative strategy:
  • precache the shell entrypoints and icons during install
  • serve navigation requests with an app-shell fallback
  • serve same-origin static assets from cache first, then network

Runtime state

• Add a small frontend service/hook for:
  • service worker registration status
  • online/offline state
  • install prompt availability
  • installed/running-standalone detection
• Keep this state client-only and independent from the auth/data hooks.

Dashboard experience

• Add a dedicated dashboard panel in the overview section named around "Демо и PWA".
• The panel explains:
  • what PWA is
  • why installability matters for demos
  • what works offline in demo mode
  • what still requires network and real backend integration
• Show compact status chips for:
  • online/offline
  • app install availability / installed state
  • offline readiness after service worker activation
• Show an install CTA only when the browser exposes an install prompt.

Offline behavior

Guaranteed offline

• Opening the installed app after it has already been loaded once
• Reopening /dashboard without network
• Demo login flow with local role selection and OTP 000000
• Viewing demo orders, metrics, notifications, and role-based dashboard sections backed by local data

Not guaranteed offline

• Supabase-backed auth and profile loading
• Any future remote integrations, push delivery, or server-dependent writes
• Fresh first load before the service worker has cached the shell

The dashboard copy must state these limits plainly to avoid overpromising.

UI content

The dashboard panel should communicate in Russian and stay concise:

• short explanation of PWA in plain language
• short explanation of why it is useful in demos
• explicit note that demo data is local, so the product can be shown without internet after first launch
• explicit note that production integrations need connectivity

File responsibilities

• public/manifest.webmanifest — install metadata
• public/service-worker.js — shell caching and offline fallback behavior
• public/icons/* — install and launcher icons
• src/main.jsx — service worker registration
• src/hooks/usePwaStatus.js — browser/PWA state
• src/components/dashboard/PwaDemoPanel.jsx — dashboard explanation and status UI
• src/pages/DashboardPage.jsx — placement of the panel in overview
• tests next to the new hook/component where it is practical

Testing strategy

• Add targeted tests for the new hook/component logic where feasible in Vitest.
• Manually verify:
  • build succeeds
  • manifest is emitted and linked
  • service worker registers
  • install prompt appears in a supported browser
  • dashboard is available offline after one online load
  • the explanatory panel reflects online/offline and install states correctly

Out of scope

• Push notification recovery or subscription flows
• Full offline write synchronization to a server
• Refactoring unrelated dashboard architecture