Building the PWA Shell and Install Experience
I’m the developer behind CrisisCore-Systems and Pain Tracker – a privacy-first, offline-first pain journal built for people who’ve been failed by “normal” health apps. I build PWAs that run entirely on your device, use real encryption, and respect trauma and crisis instead of exploiting them. Here I write about Web Crypto, IndexedDB, workers’ comp evidence, and building software from collapse.
Before someone trusts you with a log entry, they need to trust something simpler: that the app will open, behave predictably, and not get in their way.
If Parts 1–6 are about trust, Part 7 is about trust signals.
People don’t evaluate a health tool the way they evaluate a news site. They notice:
- does it open reliably?
- does it feel stable?
- does it behave like a tool, not a funnel?
Your PWA shell is the first place those questions get answered.
Before anyone believes your tracking features, they have to believe the app will be there when they need it.
The PWA shell is a promise
The “shell” is what loads before data is even visible:
- HTML/CSS/JS bundle
- routing
- offline handling
- update handling
For a privacy-first health app, the shell should feel like a local utility: immediate, predictable, and quiet.
Manifest choices that matter
Treat the web app manifest as user-facing configuration.
Decisions to be explicit about:
- Name and short name: clear, non-stigmatizing, not overly clinical
- Icons: crisp at multiple sizes (install credibility)
- Display mode: choose what best matches “tool” expectations
- Start URL + scope: avoid confusing launches into the wrong route
If a user installs your app and it opens to an error or a weird deep link, you lose trust instantly.
Install UX: never pressure, always explain
Install prompts are often used as growth hacks. Don’t.
For a health tool:
- ask at a moment of success (after the user has logged something)
- explain the benefit in plain language (“Faster access, works offline”)
- allow dismissal without nagging
If users feel coerced, they will assume surveillance.
Service worker behavior: keep it boring
Your service worker should be boring.
Good boring looks like:
- the app opens offline
- updates don’t break the current session
- cache strategy is simple and explainable
Avoid clever caching that increases uncertainty. Reliability beats optimization.
Update strategy: protect in-progress work
The biggest PWA trust break is an update that interrupts a user mid-entry.
Rules:
- never force reload while the user is editing
- present “Update available” as a choice
- offer “Refresh when ready”
In a health context, “later” is a valid answer.
Offline UX: honest and calm
Offline UX should not be dramatic.
- prefer subtle indicators (“Offline”)
- keep the primary flow working
- avoid big blocking banners
When the user is offline, they already know life is complicated. Your job is to be steady.
PWA shell quick check
1) App launches reliably with no network 2) Install prompt is optional and non-pushy 3) Updates never interrupt in-progress logging 4) Cache strategy is explainable and consistent 5) Offline state is communicated calmly
Next: Part 8 — Protecting Data: Threat Modeling for Small Teams
Next, Part 8 runs a lightweight threat-modeling exercise that fits a solo/indie team: realistic risks, pragmatic controls, and clear boundaries on what you can and can’t promise.
