Desktop PIMS Shell

Desktop PIMS Shell

apps/desktop (@yosemite-crew/desktop) is an Electron shell that wraps the web PIMS with native capabilities — offline sync, controlled-substance compliance, multi-tab, and a hardened security posture. The code under apps/desktop/src is canonical.

Screenshots

_{The Electron PIMS shell: sign-in, dashboard, organization onboarding, and native menus. Source: apps/desktop/resources/screenshots/.}

Process model

flowchart TB
    subgraph Electron
        MAIN["Main process<br/>src/main.ts"]
        PRELOAD["Preload bridge<br/>src/preload.ts"]
        REN["Renderer<br/>PIMS web app + local chrome pages"]
    end
    MAIN -- "IPC allowlist (~70 yc:* channels)" --> PRELOAD
    PRELOAD -- contextBridge --> REN
    MAIN --> PIMS["yosemitecrew.com<br/>(allowlisted origins)"]
    MAIN --> SYNC["Offline store (sql.js)"]
    REN -. "blocked: /developers, /dev-docs" .-> BROWSER["System browser"]

Loading

• Main process: src/main.ts (~1900 lines, the composition root) → build/main.js. Wires MDM/managed config → windows, tray, IPC, compliance, sync, vault, updater, idle-lock, telehealth, and a tab manager.
• Preload bridge: src/preload.ts → build/preload.js (contextIsolation bridge exposing only allowlisted IPC channels).
• Renderer: the PIMS web app loaded remotely, plus local "chrome" pages under src/pages/ (static HTML/CSS copied to build/pages): welcome, loading, offline, settings, command-palette, tabbar, whats-new, vault.
• Modular main-process code: core/ (navigation policy, IPC, tab manager, window state), shell/ (window creation + config), boot/setup.ts, ui/ (tabs, command palette, menu, tray, theming, notifications), lifecycle/ (updater, auto-rollback, crash reporting, idle/biometric lock), compliance/, sync/, utils/.

How it wraps the PIMS

• Start URL and origin allowlist in src/core/navigation-policy.ts: DEFAULT_START_URL = https://www.yosemitecrew.com/signin, allowed origins = www + apex. Overridable via env (YC_DESKTOP_START_URL, YC_DESKTOP_ALLOWED_ORIGINS, …), fed by MDM config (utils/mdm.ts).
• classifyNavigation() returns internal | external | blocked. External origins and blocked paths (/developers, /dev-docs) open in the system browser — the developer portal is deliberately pushed out of the desktop shell. deepLinkToUrl() maps yosemitecrew:// deep links to internal routes only.
• Multi-tab UI via WebContentsView with a 40px chrome strip (tabbar.html), split-view, and orientation control.

Security posture

secureWebPreferences (shell/window-config.ts): contextIsolation: true, nodeIntegration: false, sandbox: true, webSecurity: true, webviewTag: false, dedicated partition persist:yosemitecrew-pims; TLS certificate errors always rejected. The IPC boundary (src/core/ipc.ts) is a ~70-channel yc:* allowlist with validateIpcRequest() rejecting unknown channels, unexpected args, or untrusted senders. Local chrome pages ship strict per-page meta CSP (default-src 'none', *-src file:); runtime hardening via Electron fuses (scripts/apply-fuses.js).

Offline-first and compliance

• Offline sync (sync/): offline-store.ts (sql.js), offline-cache.ts, sync-engine.ts, sync-queue.ts, sync-daemon.ts — the desktop can operate and reconcile when disconnected.
• Controlled-substance / DEA compliance (compliance/): controlled-substance.ts, dea-registration.ts, dea-reminder.ts, dea-report.ts, dual-witness.ts, pmp-submission.ts, cs-export.ts, audit-log.ts, offline-audit-trail.ts — regulatory features that benefit from a native, offline-capable client.
• Telehealth launches are GetStream-only (utils/telehealth.ts), consistent with the Stream Chat stack.

Build, packaging, release

• electron-builder config inline in package.json (appId com.yosemitecrew.pims, asar on, afterPack: apply-fuses.js, afterSign: notarize.js, deep-link scheme yosemitecrew, GitHub publish). Targets: Windows NSIS + portable (x64), macOS dmg/zip (notarized), Linux AppImage/deb.
• Windows signing via Azure Trusted Signing (scripts/windows-trusted-sign.js; publisherName DuneXploration UG (haftungsbeschränkt)).
• CI release (.github/workflows/desktop-release.yml): pushing a desktop-v* tag builds, signs, and publishes a GitHub Release; workflow_dispatch produces a draft. electron-updater reads published Releases; channels (beta/latest) documented in apps/desktop/RELEASE.md. This is the only fully CI-automated release build (Release Process).

Code quality (Sonar)

sonar-project.properties (projectKey yosemitecrew_Yosemite-Crew_Desktop) excludes composition-root glue and src/pages/** from coverage. Two intentionally deferred Web:S6819 smells remain — role="dialog" on two panels in src/pages/tabbar.html (a child WebContentsView, not a top-level document). See Code Quality Gates.

Related

• Architecture Overview · Backend: Realtime, Chat, Jobs · Release Process · Code Quality Gates