feat(clients): scaffold mobile (Capacitor) + desktop (Electron) shells

Plan + decisions in CLIENTS.md (parallel mobile+desktop; desktop = technician client + existing remote-control agent host; mobile = Capacitor wrap). - desktop/: Electron technician client — loads the live Connect UI, native screen capture via setDisplayMediaRequestHandler, persisted session, external links to browser; electron-builder config for Win/Mac/Linux installers. - mobile/: Capacitor project — server.url loads Connect UI, push/camera/status-bar plugins declared, www splash fallback; iOS/Android added via `cap add`. - Reuses the existing /api/v1 + Bearer auth backend; no web-code changes. - .gitignore: ignore generated mobile/android, mobile/ios platform dirs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-30 17:49:41 +05:30
parent f517c153c1
commit 593a4677b6
10 changed files with 332 additions and 0 deletions
@@ -0,0 +1,107 @@
+# Biz Connect — Mobile & Desktop clients
+
+Native clients for Biz Connect. **The web app is the single source of truth for the UI**;
+each native client is a thin shell that loads that UI and adds the capabilities a browser
+can't provide (background push, native screen capture, OS input injection, store presence).
+
+Decisions (set by the user 2026-06-30):
+- **Build mobile and desktop in parallel.**
+- **Desktop = both pieces:** the remote-control **host** (existing `agent/`) *and* a
+  **technician desktop client** (`desktop/` — Connect in a window).
+- **Mobile = Capacitor wrap** of the existing web UI (one codebase), not a native rewrite.
+
+Backend is already client-ready (see [ARCHITECTURE.md](ARCHITECTURE.md) Phase 2): `/api/v1`,
+`Authorization: Bearer` + refresh tokens, API keys, per-tenant webhooks. The one remaining
+backend gap is **APNs/FCM push** for native mobile (needs Apple/Google credentials).
+
+---
+
+## Components
+
+| Dir | Client | Tech | What it adds over the browser |
+|-----|--------|------|-------------------------------|
+| `mobile/` | iOS + Android app | **Capacitor** loading the Connect UI | Native push (FCM/APNs), camera/mic perms, store distribution, screen capture (ReplayKit / MediaProjection) |
+| `desktop/` | Technician client | **Electron** loading the Connect UI | Native full-screen capture for screen-share; windowed app; later: tray, auto-update |
+| `agent/` | Remote-control **host** (customer) | **Electron + nut-js** *(exists, v0.2.0)* | Screen capture + **OS input injection** so a technician can control the machine |
+
+All three authenticate through the same `/api/v1` access layer (Bearer token for mobile/desktop,
+the existing consent/enroll flow for the agent).
+
+---
+
+## Why "wrap the web UI" (not rewrite)
+
+The Connect UI is already an installable PWA built from server-rendered single-file HTML.
+Pointing a native webview at the server origin means **every relative `/api` and `/ws` URL
+keeps working unchanged** — zero web-code changes — while native plugins augment it through
+the JS bridge. One codebase, three shells.
+
+Trade-off: a server-URL shell needs network at launch (fine for a remote-support tool) and
+some stores scrutinise "just a website". We mitigate by shipping real native capabilities
+(push, screen capture, deep links), and can later switch to **bundled** web assets + an
+absolute API base if offline-launch or store policy requires it.
+
+---
+
+## Phased plan
+
+### Phase A — Shells that load the live app  ← start here
+- [ ] `desktop/` Electron client: `loadURL(server)`, `setDisplayMediaRequestHandler` so
+      screen-share works natively, external links → browser, persisted session.
+- [ ] `mobile/` Capacitor project: `server.url` → Connect, app icons/splash, status bar.
+- [ ] Inject `window.__NATIVE__ = 'desktop' | 'ios' | 'android'` so the web UI can adapt
+      (e.g. hide the PWA "install" prompt, enable native push instead of Web Push).
+
+### Phase B — Native capabilities
+- [ ] **Push:** server device-token registration (`/api/v1/devices`) + a pluggable
+      `push` sender (FCM/APNs), config-gated. Mobile uses the Capacitor push plugin;
+      desktop keeps Web Push / in-app. *Needs Apple/Google creds to test end-to-end.*
+- [ ] **Mobile screen capture** for "Share Screen" from a phone (ReplayKit / MediaProjection plugin).
+- [ ] **Deep links / universal links** so a session/meeting link opens the app.
+
+### Phase C — Packaging & distribution  *(needs external accounts)*
+- [ ] Desktop installers via **electron-builder** (Win NSIS + Mac dmg); **code-signing**
+      (Win EV cert, Apple Developer ID + notarization).
+- [ ] Mobile store builds: **Apple Developer** ($99/yr) + **Google Play** ($25 once);
+      signing keys; store listings & privacy disclosures.
+- [ ] Agent host installer (signed) for customers.
+- [ ] Auto-update channels.
+
+---
+
+## Build & run
+
+### Desktop (technician client)
+```bash
+cd desktop
+npm install
+SERVER_URL=https://remote.bizgaze.com npm start     # or http://localhost:8090 in dev
+npm run dist                                         # build installers (needs electron-builder + certs)
+```
+
+### Mobile (Capacitor)
+```bash
+cd mobile
+npm install
+npx cap add android        # needs Android Studio + SDK
+npx cap add ios            # needs macOS + Xcode
+npx cap sync
+npx cap open android       # build/run from Android Studio
+npx cap open ios           # build/run from Xcode
+```
+Set the server origin in `capacitor.config.json` (`server.url`).
+
+### Agent host (existing)
+```bash
+cd agent
+npm install
+SERVER_URL=https://remote.bizgaze.com AGENT_ENROLL_TOKEN=<token> npm start
+```
+
+---
+
+## What's gated on you (external, can't be done from code alone)
+- **Apple Developer** + **Google Play** accounts (mobile store builds & push).
+- **Code-signing certificates** (Windows EV, Apple Developer ID) for trusted installers.
+- **FCM/APNs credentials** for native push.
+Everything else — the shells, the device/push backend, native plugin wiring — is built here.