SRCmail/docs/OFFLINE-CLIENT-ARCHITECTURE.md

Bulwark / VNCmail+ — Offline & Native Client Architecture Analysis

Date: 2026-08-04 (updated same day — see §7 for a strategy-changing discovery) Scope: what Bulwark (upstream bulwarkmail/webmail, forked as VNCmail+) delivers today for offline use, and what has to be built to ship Electron (desktop), Capacitor/React-Native iOS (IPA) and Android (APK) clients with local notifications, an encrypted local search index (SQLite/SQLCipher), and true offline mail.

Note on this file's persistence: ~/vncmail-plus is a shared checkout — other sessions actively commit and switch branches here. An earlier untracked copy of this doc was lost to a branch switch. Commit this file (or move it somewhere durable) if you want it to survive.

1. Current state of the webmail repo (verified against ~/vncmail-plus source)

Area	Status today	Evidence
Service worker	Installed, but caches nothing — fetch handler is a deliberate no-op so the app is never usable offline	public/sw.js:6-8,36
Web app manifest	Present, installable PWA (icons, protocol_handlers for mailto/webcal)	app/manifest.ts
Push notifications	Real Web Push: VAPID subscribe, Notification.requestPermission, SW push/notificationclick handlers, relayed through an external push relay + a preview API route	lib/web-push.ts, public/sw.js:38-42, app/api/push/preview/route.ts
Local mail cache	None. IndexedDB is used only for plugin/theme blobs; localStorage only holds device IDs and Zustand UI-state (persist()), never message bodies	lib/plugin-storage.ts, stores/account-store.ts:220
Search	Server-side JMAP Email/query only, no client index	lib/jmap/search-utils.ts
Local encryption	None for cached data. The one AES-256-GCM routine (lib/auth/crypto.ts) encrypts the session cookie server-side using node:crypto — unusable in a browser/WebView	lib/auth/crypto.ts
Mobile/desktop packaging in this repo	Nothing exists: no capacitor.config.ts, no Electron main/electron-builder, no Tauri, no fastlane/gradle/Xcode	confirmed via repo-wide find; .github/workflows/*
JMAP client portability	lib/jmap/client.ts is pure fetch(), no Node-only APIs — portable into a WebView/Electron renderer unchanged	grep for node:/require( in lib/jmap/* = zero hits

Multi-account scope: confirmed YES — the offline cache must support multiple simultaneous Stalwart accounts per device (matches the webmail's existing account-registry store). This multiplies SQLCipher key-management work (§3/§7): one isolated key per account, not one global key.

2. The fork in the road: shell strategy

Option A — Native shell over a remote WebView. Capacitor/Electron just point at the hosted Bulwark URL. Cheapest, ships an APK/IPA/desktop binary fast, gets native push — but is not offline.

Option B — True offline-first client. The client authenticates and syncs JMAP data directly, keeps a local encrypted store, and only needs connectivity to sync, not to read.

Recommendation stands: Electron first (Option-B-lite is nearly free there — see §4), mobile starts with Option A, then graduates to Option B — but see §7: for mobile, "graduate to Option B" likely means extending an existing app, not building one from scratch.

3. Build-vs-buy matrix (webmail-repo-only view — see §7 for the revised mobile view)

Component	Off-the-shelf	What you build yourselves
Capacitor shell (iOS/Android project scaffolding)	Capacitor CLI generates both native projects	Splash/icons, deep-link config, capacitor.config.ts tuning
Local SQLite	@capacitor-community/sqlite — ships native SQLCipher support on iOS/Android; web fallback via jeep-sqlite/wa-sqlite	Schema, JMAP→SQLite mapping, migrations
SQLCipher key lifecycle	Native Keychain/Keystore APIs (via Capacitor Secure Storage) store the raw key	Key derivation/rotation, per-account keys (multi-account confirmed §1), wipe-on-logout
Full-text search	SQLite FTS5 ships free with SQLite	Tokenizer choice, incremental indexer fed by the sync engine
Native push	@capacitor/push-notifications wraps FCM/APNs	Relay extension, device-token registration, notification-tap deep-linking
Electron desktop	electron-builder; Electron's own cross-platform Notification API	Main process booting the existing standalone Next.js server; auto-update wiring
Background sync	iOS BGTaskScheduler, Android WorkManager	The actual poll/backoff/delta-fetch job logic
Biometric app-lock	capacitor-native-biometric	UI/UX, fallback-to-passcode flow
Store release pipeline	Fastlane/EAS-style CI, Apple/Google developer accounts	Signing config, CI secrets, store metadata

4. Why Electron is the cheap win

Electron has no server-dependency problem: bundle the standalone Next.js server (the same artifact the Dockerfile already produces) inside Electron's Node runtime, open a BrowserWindow against localhost. Reuses 100% of the existing app including app/api/**. Native Notification API replaces Web Push entirely on desktop. Ships well before mobile Option B.

5. Phased roadmap

1. Fix the service worker — today's SW intentionally caches nothing (sw.js:36). Add Workbox-style precaching of the app shell/static assets. Cheap, immediate PWA-offline-shell improvement, no architecture change.
2. Electron desktop (§4) — bundle standalone server + BrowserWindow + native Notification + electron-builder packaging.
3. Capacitor mobile, Option A (remote shell) — WebView on the hosted instance, native push registration bridged into the relay, biometric app-lock. Ships an installable APK/IPA fast; not offline yet. Revisit against §7 before starting — extending vncmail-native may replace this step entirely rather than complement it.
4. JMAP sync engine + SQLite/SQLCipher store — design delta-sync via Email/changes/Mailbox/changes; local schema, one key per account (§1); move auth off the Next-only encrypted cookie into secure storage so mobile can talk to Stalwart directly. §7: vncmail-native already has a cruder version of the "local cache" half of this (bulk AsyncStorage download) — the delta-sync/SQLite/SQLCipher/FTS half is still greenfield there too, but auth/JMAP wiring is not.
5. FTS index + offline compose/outbox — SQLite FTS5 population job; offline-composed messages queued and replayed via JMAP Email/set on reconnect; conflict handling.
6. Platform hardening — background refresh scheduling, Apple export-compliance declaration (SQLCipher/AES in the binary triggers ITSAppUsesNonExemptEncryption), signing/release CI.

6. Open questions — status

• Does the referenced upstream React Native app already solve native push/device-pairing? RESOLVED — see §7.
• Is Bulwark upstream planning native clients? Partially answered by §7: yes, bulwarkmail/native is that plan, already public, beta/WIP. Still worth watching its upstream activity before diverging further, since pulling upstream improvements is cheaper than re-diverging an AGPL fork.
• Multi-account scope — RESOLVED, see §1.

7. 2026-08-04 discovery: an upstream React Native app already exists — re-scope Phase 2

bulwarkmail/native (public, AGPL-3.0-only, Expo SDK 54, beta/WIP) is a React Native mobile client for Bulwark. Forked to brvncde-dotcom/vncmail-native. It already ships:

• Multi-account JMAP sign-in against any server (e.g. Stalwart).
• QR-code cross-device pairing — src/screens/LoginScreen.tsx + QrScanModal + redeemPairingCode/OAuth handoff in src/lib/oauth.ts. This is the "QR-code SSO login and device pairing" feature referenced in the webmail's CHANGELOG.md:207.
• Android push notifications via FCM, dispatched through a second public upstream repo, bulwarkmail/relay (also AGPL-3.0) — this is the actual service behind the webmail's DEFAULT_RELAY_BASE_URL, resolving the open question from the original Phase-2 plan about where that relay's source lives. It terminates JMAP PushSubscription pushes and forwards to FCM (mobile) or Web Push (PWA); a single Bulwark-hosted instance serves every opted-in client so self-hosters don't need their own Firebase project — or you can self-host it (Docker compose provided) if you want push traffic to never leave VNC infrastructure. Decided: self-host. Forked to brvncde-dotcom/vncmail-relay. Remaining: dedicated Firebase project for FCM credentials, a VAPID keypair, a microk8s deploy alongside vncmail-plus (per vnclagoon-suite-microfrontends), and repointing both vncmail-plus (DEFAULT_RELAY_BASE_URL) and vncmail-native at the self-hosted instance. Sequenced in the VNCprodbuild skill's Phase 2 step 0.
• A basic offline mail cache already: src/lib/offline-sync.ts (155 lines) bulk-downloads the last N days of mail via Email/query+Email/get into src/stores/offline-cache-store.ts (AsyncStorage-backed, size-capped, evicts oldest), with live progress UI (OfflineCacheBanner.tsx). This is not the delta-sync/SQLite/SQLCipher/FTS engine Phase 2 called for — it's a periodic bulk re-download, not incremental Email/changes sync, and storage is plain JSON in AsyncStorage, not an encrypted database — but auth, JMAP wiring, and the UI shell around "offline mail" already exist.
• Android release pipeline (.github/workflows/release-android.yml, sideload APK from GitHub Releases) and an iOS release pipeline (release-ios.yml, docs/ios-release.md, TestFlight) already exist — iOS builds, just without push (see below).

Still genuinely missing (confirmed against its own README + source):

• iOS push notifications and client certs — Android-only so far.
• No SQLite/SQLCipher/FTS anywhere (@react-native-async-storage/async-storage + expo-secure-store only) — the encrypted-local-index work is still fully greenfield. Resolved 2026-08-04: use expo-sqlite's official useSQLCipher config-plugin option (Android/iOS/macOS) rather than a third-party binding. Unusable in Expo Go, so this forces a custom dev client for development going forward — accepted. Stay Continuous-Native-Generation (don't commit ios/android, let expo prebuild regenerate them) rather than going fully bare, since a committed native tree would conflict on every future merge from upstream bulwarkmail/native. Detail in the VNCprodbuild skill's status log.
• Filters & rules, S/MIME, plugins, themes, file storage are UI stubs only.
• No Play Store distribution yet.

Strategic implication: for the mobile leg of the native-client roadmap, extending vncmail-native is very likely cheaper than building a Capacitor wrapper around the webmail from scratch — it already has the parts that were the most speculative/decision-heavy in the original Phase-2 plan (auth, pairing, push wiring, multi-account, a working offline-mail UX shell). The remaining work narrows to: iOS push, replacing the AsyncStorage bulk-cache with a real Email/changes delta-sync engine into SQLite/SQLCipher, an FTS5 index, and an offline-compose/outbox queue — i.e., roughly roadmap steps 4–6 above, now scoped against an existing app instead of a blank one. This should be a formal decision gate before touching Phase 2 further: adopt vncmail-native as the mobile client going forward (dropping/deferring the Capacitor-wraps-webmail plan for mobile), or keep both in parallel. Recommend adopting it — duplicating auth/pairing/push work that already exists and works has no upside.