PWA and Offline

PWA and Offline Mode

DOCSight is a mobile-first Progressive Web App. You can install it from a modern browser and open it like an app from your phone, tablet, or desktop.

Offline support is intentionally conservative. DOCSight is a monitoring tool, so it should never make stale modem or connection data look live. When the network is unavailable, the app can keep the dashboard shell usable, but live readings, API data, modem polls, and health checks still require a connection to the DOCSight server and your modem.

What you can expect

• Install DOCSight from supported browsers as a standalone app.
• Open the installed app at the dashboard start URL.
• Use home-screen or browser shortcut entries for common sections where the platform supports them.
• Keep the core app shell, styles, icons, fonts, and built-in module assets available from the browser cache.
• See a clear offline banner when DOCSight is offline or when a cached shell is being shown.
• Avoid confusing cached pages with fresh monitoring data.

Installability

DOCSight ships a web app manifest with:

• App identity: DOCSight, root scope, and stable app id /.
• Standalone display mode for installed-app surfaces.
• Start URL: /?source=pwa.
• 512x512 PNG and SVG icons.
• Narrow and wide dashboard screenshots for install prompts and app stores that use manifest screenshots.
• Shortcuts for the live dashboard, event log, and channels.

Install prompts depend on the browser and operating system. If your browser does not show an install button automatically, use the browser menu and choose Install app, Add to Home Screen, or the closest equivalent.

Offline behavior

DOCSight uses a service worker with separate strategies for app shell, static assets, and live data.

App shell

The dashboard shell is handled with a network-first strategy:

1. Try to load the current dashboard from the DOCSight server.
2. Store a successful shell response for later.
3. If the network fails, fall back to the cached shell.
4. Mark the cached response as an offline shell so the UI can show the offline state.

When a cached shell is used, DOCSight adds an offline marker internally and shows the offline status banner in the UI.

Static assets

Static assets use a cache-first strategy:

• CSS and JavaScript
• icons and manifest
• fonts and bundled vendor assets
• built-in module styles and scripts
• manifest screenshots

This keeps the installed app responsive and avoids blank screens when the network is temporarily unavailable.

Live data and API requests

Live data is not generically cached by the service worker.

Requests such as API calls, health checks, modem polling, and mutating actions go to the network. If the DOCSight server, modem, or local network is unavailable, those requests should fail visibly instead of reusing stale values as if they were fresh.

This is deliberate. Signal levels, errors, speedtest state, outages, and health summaries are time-sensitive. Showing old values as live data would make the monitoring experience less trustworthy.

Offline banner and read-only state

When DOCSight detects that the browser is offline or that the service worker returned a cached offline shell, it shows an offline banner.

The offline state means:

• The visible app shell may come from cache.
• Live dashboard values may not refresh.
• The refresh button is kept disabled while the app is in the offline shell state.
• You should reconnect before treating health status, modem values, or event state as current.

What offline mode does not do

DOCSight does not currently provide:

• Background sync of modem readings.
• Offline creation of new measurements or incidents that sync later.
• Cached API snapshots presented as current values.
• A complete historical offline browser database.
• Push notifications from the PWA service worker.

Historical data is still stored by the DOCSight backend, usually in SQLite. The PWA cache is only for browser-side app shell resilience, not a replacement for DOCSight's database or backups.

Local development and testing

For local development on localhost or 127.0.0.1, DOCSight normally disables the service worker. This avoids stale development caches while editing the UI.

The PWA test gate can opt in explicitly with:

?enable-sw-test=1

That test mode lets automated browser tests verify service worker registration and offline shell behavior without changing the normal local development experience.

Troubleshooting

The install button does not appear

Check that you are using a supported browser, that DOCSight is served from a secure context, and that the manifest is reachable at /static/manifest.json.

For local network installs, browser behavior varies. Some browsers allow installation from private-network origins, while others are stricter.

The app shows an offline banner

The browser is offline, the DOCSight server cannot be reached, or the service worker is serving a cached shell after a failed network request.

Reconnect to the DOCSight host and reload before relying on current modem values.

Data looks stale after reconnecting

Refresh the app after connectivity returns. If the browser still behaves unexpectedly, close the installed app and reopen it. As a last resort, clear site data for the DOCSight origin from your browser settings.

Related pages

• Dashboard
• Installation
• Configuration
• Backup and Restore