# 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