Specification: Desktop Electron EHR Client
Domain: Platform client (Electron desktop)
Version: 1.0
Date: 2026-03-31
Status: Normative for the desktop product surface
Extends: OFFLINE_FIRST_AND_CLIENT_SYNC.md, offline-first/SPEC.md
Related documents:
- TECHNICAL_REQUIREMENTS.md
- SOLUTION_DESIGN.md
- UI_AND_DESIGN_PARITY.md
- governance-auth/README.md
- REGIONAL_PROFILE.md
- AI_PLATFORM.md
1. Purpose and scope
1.1 Purpose
Deliver a desktop Electron application that lets authorized clinical and administrative users use the Ghasi EHR when network connectivity is missing or unreliable. The client SHALL:
- Persist work locally and synchronize to the platform when connectivity and valid auth allow.
- Respect tenant isolation, licensing, access policy, and auditability (server remains authoritative for global invariants).
- Present a user experience and visual design consistent with
apps/ehr-web(Berry template, MUI, shared packages).
1.2 In scope
- Electron main, preload, and renderer responsibilities and security boundaries.
- Local encrypted store, read models, drafts, and outbound mutation queue (first-class on desktop even if
ehr-webdoes not yet ship a unified platform outbox). - Persona-aware navigation and feature availability driven by IAM + access-policy + licensing (same conceptual model as web).
- Offline UX: connectivity state, sync progress, conflict surfacing, and safe degradation for online-only capabilities.
1.3 Out of scope
- Replacing or redefining per-module clinical rules (see each module
SPEC.md). - Choosing server-side idempotency implementation details inside NestJS services (documented in module specs and code).
- Non-EHR personas that are exclusively web-only unless product explicitly adds them here.
2. Personas and platform mapping
Personas are product labels; enforcement is via JWT identity, tenant, hierarchy context, roles, and access-policy decisions (see governance-auth/README.md).
| Persona (product) | Typical responsibilities | Notes |
|---|---|---|
| Clinician | Patient chart, orders, notes, vitals, results review, medications, allergies, problems | Dense clinical UI; same module set as EHR web where licensed. |
| Nurse / care staff | Vitals, documentation, tasks as licensed | May be a role bundle; not a separate codebase. |
| Registration | Patient registration, demographics, duplicate checks | Offline queue aligns with registration idempotency patterns. |
| Administrator | Tenant/org configuration, users, policies (within scope) | May use /api/... platform surfaces; some flows online-only. |
| Platform operator | Cross-tenant operations | Often restricted; may be online-only or excluded from desktop v1. |
The desktop app SHALL not hard-code permissions in the UI beyond optimistic hiding; server gates remain authoritative (403, licensing, access-policy).
3. Functional requirements (FR-DSK-###)
| ID | Requirement |
|---|---|
| FR-DSK-001 | The desktop app SHALL operate with full local UX for workflows that the product marks offline-capable (navigation, forms, local validation, cached reads) when the network is unavailable. |
| FR-DSK-002 | The desktop app SHALL queue eligible writes with a stable clientMutationId and/or Idempotency-Key per offline-first TECHNICAL_REQUIREMENTS.md for APIs that support replay. |
| FR-DSK-003 | When connectivity returns, the app SHALL sync queued mutations with bounded retries, exponential backoff with jitter on 429, and no infinite retry on 401/403. |
| FR-DSK-004 | The app SHALL surface conflicts (e.g. 409, duplicate detection, optimistic lock) with user-visible resolution paths per module policy; silent overwrite of regulated PHI SHALL NOT occur. |
| FR-DSK-005 | The app SHALL show clear global connectivity and per-area sync status (e.g. pending, syncing, failed, conflict). |
| FR-DSK-006 | Features that require live server or third-party live integration SHALL be labeled online-only and SHALL degrade gracefully offline (read-only cache, queued intent, or disabled UI with explanation). |
| FR-DSK-007 | The app SHALL respect module licensing and feature flags from config-resolver / licensing; unlicensed modules SHALL be hidden or blocked consistent with MODULE_SHARED_STANDARDS.md. |
| FR-DSK-008 | The app SHALL load message catalogs and locale consistent with tenant/user effective config (CONFIG_MODEL.md) and SHALL reuse @ghasi/i18n / shared keys with apps/ehr-web where applicable, with a documented fallback chain (e.g. requested locale → tenant default → en). |
| FR-DSK-009 | The app SHALL support both LTR and RTL layout (not only translated strings): MUI theme direction, root dir and lang on the HTML document, and navigation/chrome mirroring per REGIONAL_PROFILE.md and MODULE_SHARED_STANDARDS.md §4. |
| FR-DSK-010 | For mixed-direction content (MRNs, codes, phone numbers, Latin tokens inside RTL UI), the app SHALL use <bdi>, dir="auto", or equivalent so bidirectional text renders correctly in forms, tables, and clinical widgets. |
| FR-DSK-011 | The app SHALL persist the user’s locale and text-direction preference where product requires (local store; sync to server when the platform exposes a preference API), without breaking tenant isolation. |
| FR-DSK-012 | Cloud AI (assistive features) SHALL use the controlled platform path only: HTTPS to Kong → ai-orchestrator per AI_PLATFORM.md; no ad-hoc vendor API keys or direct browser-to-vendor model calls from the renderer. |
| FR-DSK-013 | When offline or when cloud AI is unavailable, cloud inference SHALL degrade per AI_PLATFORM.md §8 (e.g. queue draft text locally, disable feature, or switch to on-device inference if enabled by policy). |
| FR-DSK-014 | On-device / local inference MAY be offered only when tenant policy and deployment security review approve; PHI handling, human oversight for record-bound output, and audit expectations remain per AI_PLATFORM.md §5–9. |
| FR-DSK-015 | Scheduling and appointments (where licensed) SHALL present parity-rich UI with ehr-web-aligned Berry/MUI patterns (calendar, slot views, resource columns); live slot search and server-confirmed booking may be online-first while cached rosters and queued booking intents follow offline-first module rules (see specs/modules/scheduling/). |
| FR-DSK-016 | The app SHALL support desktop-appropriate notifications for scheduling (and other time-sensitive workflows): OS-level notifications when permitted, in-app notification center consistent with design parity, and clear behavior when offline (no silent loss of user-visible reminders). |
4. Non-functional requirements (NFR-DSK-###)
| ID | Requirement |
|---|---|
| NFR-DSK-001 | PHI at rest on device SHALL meet encryption and wipe expectations in COMPLIANCE_SECURITY.md and TECHNICAL_REQUIREMENTS.md. |
| NFR-DSK-002 | Tokens and secrets SHALL NOT be exposed to untrusted renderer code; use preload and OS secure storage where applicable. |
| NFR-DSK-003 | Logs SHALL minimize PHI (ids and codes, not raw demographics) per platform standards. |
| NFR-DSK-004 | Automated tests SHALL cover sync, idempotency replay, conflict paths, and tenant isolation for offline-capable flows per TESTING_STANDARDS.md. |
| NFR-DSK-005 | Update channel (auto-update) SHOULD be documented and secured (signed artifacts); exact mechanism in TECHNICAL_REQUIREMENTS. |
| NFR-DSK-006 | Localization: date/time/number/currency formatting SHALL follow active locale and REGIONAL_PROFILE.md; E2E SHALL assert dir and shell layout for at least one RTL locale (see TECHNICAL_REQUIREMENTS.md). |
5. Online-only capabilities (representative)
The following depend on live connectivity or external systems; behavior offline MUST be explicitly defined (disabled, cached read-only, or queue-for-later) per module:
| Area | Typical online-only or limited-offline behavior | Pointer |
|---|---|---|
| Real-time messaging / presence | Live delivery, typing presence | specs/modules/messaging/ |
| External payer / clearinghouse | X12 / real-time eligibility | specs/modules/claims/, insurance/ |
| Some imaging / PACS streaming | Streaming viewers, DICOMweb latency | specs/modules/radiology-pacs/ |
| AI — cloud orchestration | Inference via Kong → ai-orchestrator | AI_PLATFORM.md, specs/modules/ai-orchestrator/ |
| AI — on-device | May work offline when policy enables local engine; still subject to safety and audit rules | AI_PLATFORM.md §8 |
| Cross-tenant platform admin | May be restricted to network trust zone | specs/modules/platform-admin/ |
| Scheduling — real-time free/busy, instant slot holds | Often online-first; offline may show cached schedules and queued requests | specs/modules/scheduling/ |
Exact offline phases per module: see each module SPEC.md / TECHNICAL_REQUIREMENTS.md and BACKEND_AND_SERVICE_MAP.md.
6. Acceptance criteria (Gherkin)
Feature: Offline operation
Scenario: User continues charting without network
Given the device has no route to Kong
When an offline-capable workflow is completed
Then changes are persisted locally
And the outbound queue shows pending sync
And online-only actions are unavailable or clearly explained
Feature: Sync on reconnect
Given valid JWT or refresh path
When connectivity to Kong is restored
Then queued mutations are submitted with idempotency headers
And successful server responses reconcile local state
Feature: Tenant isolation
Given a user switches tenant context on the server
When local data is loaded
Then local data is not merged across tenants
Feature: RTL layout
Given the user selects an RTL locale (e.g. Arabic)
When the application shell loads
Then the document direction is rtl
And primary navigation mirrors relative to LTR
And MUI theme direction matches document direction
Feature: Mixed-direction clinical identifiers
Given RTL layout is active
When an MRN or code containing Latin digits is shown
Then bidirectional rendering preserves readability without corrupting token order
7. Open questions (product)
- Priority order of modules for full offline write support (registration vs notes vs orders vs scheduling).
- Administrator and platform operator depth on desktop vs web-only admin tools.
- Auto-update vendor (e.g. electron-builder + S3/GitHub Releases) per deployment.