110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# 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
|