eHealth Desktop Platform — Implementation-Ready Requirements (Electron)
Status: Normative for desktop client scope (extends SPEC.md, TECHNICAL_REQUIREMENTS.md, SOLUTION_DESIGN.md)
Stack decision: Electron (main + preload + renderer), React + MUI + Vite, TypeScript strict — not .NET/Avalonia.
Companion platform docs: OFFLINE_FIRST_AND_CLIENT_SYNC.md, offline-first/SPEC.md, AI_PLATFORM.md, COMPLIANCE_SECURITY.md, API_PATH_CONVENTIONS.md
Purpose: Single hierarchical spec suitable for Jira epics/stories and engineering kickoff. Module-specific clinical rules remain in each specs/modules/<module>/; this document binds desktop + offline + AI + integration behavior across clinical, laboratory, pharmacy, imaging, and administrative deployments, with a modular shell driven by license and access entitlements.
0. Stack alignment (replaces Avalonia / MVVM)
| Layer | Requirement |
|---|
| Shell | Electron (LTS track; version pinned in repo). |
| UI | React + MUI + Emotion; align major versions with apps/ehr-web and shared packages (@ghasi/design-system, @ghasi/widgets where applicable). |
| Bundler | Vite for renderer and preload; Electron Forge (or equivalent) for dev/package. Do not embed Next.js App Router as the primary desktop UI. |
| State / data | TanStack Query (or equivalent) for server-shaped data; feature folders; no MVVM — use React hooks and explicit view-model hooks where useful. |
| Privileged I/O | Main process only: SQLite, file paths, auto-update, optional ONNX/native workers; preload exposes minimal typed IPC (contextBridge); renderer untrusted (nodeIntegration: false). |
| Backend | NestJS microservices behind Kong; Postgres per service (server-side). |
| Events | NATS / JetStream is server-only. The desktop SHALL NOT subscribe to NATS; it consumes HTTPS (REST/JSON, FHIR as exposed) and optional SSE/WebSocket only if explicitly exposed via Kong with auth. |
| Offline | SQLite in main (e.g. better-sqlite3), outbox, sync scheduler; renderer uses IPC façade only. |
| AI | Cloud: Kong → ai-orchestrator per AI_PLATFORM.md. Local: ONNX Runtime in main or dedicated subprocess, typed IPC to renderer; no ad-hoc vendor keys in renderer. |
1. Functional requirements
1.1 Cross-cutting (all modules)
| ID | Requirement |
|---|
| REQ-DESK-FR-001 | The app SHALL enforce tenant isolation for all local rows and queued mutations (tenantId scoping). |
| REQ-DESK-FR-002 | Offline-capable workflows SHALL persist locally and enqueue writes with clientMutationId / Idempotency-Key per offline-first TECHNICAL_REQUIREMENTS.md. |
| REQ-DESK-FR-003 | Online-only workflows SHALL be labeled in UX and SHALL degrade (disabled, read-only cache, or queue-for-later) per module policy — see §1.8. |
| REQ-DESK-FR-004 | Permissions SHALL be enforced on the server; UI MAY hide controls optimistically; 403 remains authoritative. |
| REQ-DESK-FR-005 | Licensing and feature flags SHALL drive module visibility consistently with web (MODULE_SHARED_STANDARDS.md). |
| REQ-DESK-FR-006 | Audit-relevant actions SHALL be traceable to user, device app version, and correlation id on sync requests where APIs support it. |
| REQ-DESK-FR-007 | The shell SHALL be modular: routes, navigation, and feature entry points SHALL be driven by an entitlement resolution pipeline (license ⊕ role ⊕ access-policy ⊕ feature flags) — see §1.10. |
| REQ-DESK-FR-008 | Persona / site type (e.g. acute clinic, laboratory site, pharmacy site, imaging center) MAY change default landing modules and pinned nav items without forking the codebase — configuration-driven. |
| REQ-DESK-FR-009 | No licensed module SHALL register background sync or scheduled jobs that hit APIs for that module (avoid hidden calls for unpaid surfaces). |
1.2 EHR (patient intake, ROS, encounters, notes, orders, problems, allergies, vitals, immunization, scheduling)
| ID | Requirement |
|---|
| REQ-DESK-FR-010 | Patient intake / registration: capture demographics and identifiers; duplicate search MAY require network — document offline as draft + queue or blocked per registration spec. |
| REQ-DESK-FR-011 | ROS / encounters / notes: support draft offline; on sync, enforce versioning / optimistic lock per service; surface 409 conflicts with user resolution. |
| REQ-DESK-FR-012 | Orders (labs, meds, imaging): distinguish unsigned draft vs signed committed per clinical policy; some order types MAY be online-only (e.g. real-time interaction checks). |
| REQ-DESK-FR-013 | Problems / allergies / medications: local validation against cached terminology; new critical allergies SHALL follow module rules for immediate sync attempt or warning when offline (product-defined per jurisdiction). |
| REQ-DESK-FR-014 | Vitals / immunizations: offline entry with queued POST; schedule conflicts (immunization series) reconciled on server response. |
| REQ-DESK-FR-015 | Scheduling: cached calendars and queued booking intents when offline; live slot search / instant holds MAY be online-first per specs/modules/scheduling/. |
1.3 Radiology / PACS (summary)
| ID | Requirement |
|---|
| REQ-DESK-FR-020 | Orders and report viewing SHALL follow module offline rules; streaming viewers / large DICOM MAY require network — provide progressive degradation (metadata only, deferred fetch). |
| REQ-DESK-FR-021 | Embedded virtual visit / Meet (if applicable): sandboxed BrowserView / webview, allowlisted tenant Jitsi host per MOBILE_AND_DESKTOP_CLIENTS.md. |
Detailed imaging-site workflows: §1.13.
1.4 Secure messaging, notifications, virtual care
| ID | Requirement |
|---|
| REQ-DESK-FR-030 | Secure messaging: live threads are typically online-first; allow read-only cache of recent threads where policy permits. |
| REQ-DESK-FR-031 | Notifications: OS notifications when permitted; in-app notification center; no silent drop of time-critical items — show pending sync state. |
| REQ-DESK-FR-032 | Virtual care: join flows SHALL be online-only unless product defines offline join (unlikely); document clearly. |
1.5 Care plans, medication management, e-prescribing
| ID | Requirement |
|---|
| REQ-DESK-FR-040 | Care plans: offline draft + sync; goal conflicts resolved on server. |
| REQ-DESK-FR-041 | Medication management: reconciliation views SHALL prefer fresh server data when online; offline shows stale-as-of timestamp. |
| REQ-DESK-FR-042 | E-prescribing: submission to gateway/clearinghouse is online-only; local UI MAY prepare draft Rx and queue until connectivity; controlled substance rules per locale SHALL be server-gated. |
1.6 Documents management
| ID | Requirement |
|---|
| REQ-DESK-FR-050 | Upload/download SHALL use main-process or scoped file APIs; virus scan / policy on server. |
| REQ-DESK-FR-051 | OCR (AI): local ONNX or cloud OCR via ai-orchestrator only; PHI handling per AI_PLATFORM.md; user confirm before committing extracted text to chart. |
1.7 Billing (cross-site)
| ID | Requirement |
|---|
| REQ-DESK-FR-062 | Billing (claims, invoices, payments): submission to payers online-only; local MAY store draft charges and printable statements per policy. |
Laboratory- and pharmacy-specific billing touchpoints (e.g. charge capture tied to accession or dispense) SHALL follow the owning module specs; desktop SHALL surface errors from billing APIs without double-posting when sync retries.
1.8 Population health, reporting, admin
| ID | Requirement |
|---|
| REQ-DESK-FR-070 | Population health (cohorts, registries, dashboards): typically aggregate/server-computed — online-first; allow cached snapshot with as-of time when product approves. |
| REQ-DESK-FR-071 | Reporting (operational + clinical): heavy reports run server-side; desktop displays exports or paginated results; offline MAY allow cached PDFs only. |
| REQ-DESK-FR-072 | Admin (providers, facilities, DAG, users, roles, access-policy, tenants, branding): many flows online-only; read-only cache for labels acceptable; mutations MUST NOT silently queue without explicit admin idempotency design. |
1.9 AI-first features (summaries, suggestions, search, OCR)
| ID | Requirement |
|---|
| REQ-DESK-FR-080 | Cloud LLM/NLP SHALL use Kong → ai-orchestrator only; tenant policy and licensing gates. |
| REQ-DESK-FR-081 | Local ONNX MAY run for latency/offline when enabled; no silent write to legal record — human action to accept. |
| REQ-DESK-FR-082 | Semantic search (if offered) SHALL respect access-policy and tenant; implementation may be server or embedded index per architecture review. |
| REQ-DESK-FR-083 | Suggestions for orders/diagnoses SHALL be non-authoritative and attributable in audit when accepted. |
1.10 Modular shell, licensing, roles, and permissions
The desktop app is used across clinical, laboratory, pharmacy, and imaging contexts; one shell MUST adapt without separate branded forks. Entitlements combine tenant license SKUs, config-resolver / feature flags, IAM roles, and access-policy (resource/action).
| ID | Requirement |
|---|
| REQ-DESK-FR-090 | The renderer SHALL obtain a resolved capability map (at minimum: module on/off, feature on/off, route allow/deny, read vs write per resource class) from authoritative server responses (e.g. bootstrap after login + refresh on token/policy change). Optimistic UI hiding is allowed; 403/404 from APIs remains the compliance backstop. |
| REQ-DESK-FR-091 | Licensed but not purchased: module entry points SHALL not appear in primary navigation (or SHALL appear disabled with a consistent “not licensed” explanation — product SHALL pick one pattern per module class and document it). |
| REQ-DESK-FR-092 | Licensed but forbidden by role/access-policy: the user MAY see a placeholder or read-only surface (e.g. “no access”) rather than a broken route; deep links to forbidden routes SHALL fail safe with actionable messaging. |
| REQ-DESK-FR-093 | Feature-level toggles (e.g. “inventory adjustments”, “signed report release”, “QC batch”) SHALL be independent of module shell visibility where product defines sub-features; sub-features SHALL map to permission keys or policy actions with stable ids for audit. |
| REQ-DESK-FR-094 | Navigation model: sidebar / module hub items SHALL be data-driven from the capability map; order and grouping MAY vary by persona or site profile (lab vs pharmacy vs imaging). |
| REQ-DESK-FR-095 | Command palette / quick open (if present) SHALL filter targets by the same capability map — users MUST NOT discover hidden admin URLs that bypass policy (server still enforces). |
| REQ-DESK-FR-096 | Lazy loading: feature bundles for optional modules SHOULD load only when licensed and permitted to reduce attack surface and startup cost (see REQ-DESK-NFR-052). |
| REQ-DESK-FR-097 | Tenant switch (if applicable): local cache, outbox, and module visibility SHALL reset or reconcile per TR-DSK-013 / tenant isolation rules without leaking entitlements across tenants. |
| REQ-DESK-FR-098 | Telemetry (if enabled): SHALL record module feature usage without PHI; SHALL not log denied entitlement probes at verbose level in production. |
1.11 Laboratory (LIS / lab operations) — workflows
Applies when the deployment licenses laboratory / LIS surfaces (collection sites, hospital lab, reference lab operations). Detailed clinical rules: specs/modules/laboratory-lis/ (and related CPOE/order flows).
| ID | Requirement |
|---|
| REQ-DESK-FR-100 | Order intake / worklist: display incoming lab orders (from CPOE/EHR) with priority, collection type, and patient/context identifiers; support filters (status, location, panel). |
| REQ-DESK-FR-101 | Collection workflow: scheduled vs stat collection; specimen labels and barcode/identifier capture (scanner integration via main or HID keyboard wedge — document); collection time and collector attribution. |
| REQ-DESK-FR-102 | Accessioning / receiving: match specimens to orders; reject / partial receive paths with reason codes; chain-of-custody fields per module policy. |
| REQ-DESK-FR-103 | Result entry / review: manual or instrument-fed results per integration; abnormal flags, reflex suggestions online-first where rules live server-side; critical value escalation typically online-only with local acknowledgment cache when policy allows. |
| REQ-DESK-FR-104 | Panels / components: display panel membership, reference ranges (age/sex aware when server provides), units per REGIONAL_PROFILE.md. |
| REQ-DESK-FR-105 | QC / instrument ops: often online or facility network dependent; if exposed in desktop, treat as online-first with clear offline messaging (no silent QC submission). |
| REQ-DESK-FR-106 | Offline / degraded: allow draft collection events and queued mutations only for APIs that are idempotent and approved in module spec; result release and critical callbacks SHALL NOT pretend success offline unless explicitly designed with outbox + retry and duplicate-safe server handlers. |
| REQ-DESK-FR-107 | Role separation: collection, technical, pathologist/authorizing, QC roles SHALL map to permission-gated screens (hide or read-only per REQ-DESK-FR-090+). |
1.12 Pharmacy — workflows
Applies to inpatient/outpatient pharmacy operations when licensed. Rules for e-prescribing and controlled substances remain in medication / pharmacy module specs.
| ID | Requirement |
|---|
| REQ-DESK-FR-110 | Prescription queue: new / refill / pending verification queues with patient, drug, prescriber, priority; pharmacist verification step gated by permission (e.g. pharmacy.verify). |
| REQ-DESK-FR-111 | Dispensing workflow: fill → check → label → deliver states; barcode scan for NDC / package verification where required; partial fills per policy. |
| REQ-DESK-FR-112 | Inventory: stock levels, receiving, adjustments, locations (vault/cooler/floor); online-first when connected to inventory service; offline MAY allow read-only cache or queued adjustments only if module explicitly supports idempotent replay. |
| REQ-DESK-FR-113 | Compounding / specials (if licensed): separate feature flag; batch and beyond-use fields as per module; online validation when required. |
| REQ-DESK-FR-114 | Regulatory / audit: controlled substance actions SHALL require authenticated session and server validation for schedule rules; desktop SHALL not bypass EPCS or local regulator flows — draft locally, submit online. |
| REQ-DESK-FR-115 | Counseling / handoff: document counseling offered/refused when required; print / handout via OS print APIs from main or sandboxed print path. |
| REQ-DESK-FR-116 | Offline / degraded: dispense and inventory commit SHALL follow explicit offline policy (often blocked or queue with strong warnings); UI SHALL show stale-as-of for drug interaction and formulary data when offline. |
| REQ-DESK-FR-117 | Role separation: technician vs pharmacist vs inventory manager screens SHALL respect entitlements; segregation of duties enforced server-side with 403 on violation. |
1.13 Imaging / radiology — workflows
Applies to imaging centers and hospital radiology when RIS/PACS or imaging modules are licensed. Viewer integration may be embedded web, deep link, or third-party launch — document per tenant.
| ID | Requirement |
|---|
| REQ-DESK-FR-120 | Imaging worklist: modality worklists (CT/MR/US/XR…) with status (scheduled, in progress, completed), priority, contrast flags as exposed by API; sync when online. |
| REQ-DESK-FR-121 | Order and appointment alignment: link imaging orders to slots / resources per scheduling module; conflicts surfaced server-side. |
| REQ-DESK-FR-122 | Prior studies: list prior exams for comparison with metadata (date, modality); full prior fetch may require network; cache thumbnails only if policy allows. |
| REQ-DESK-FR-123 | Viewer: launching diagnostic viewer SHALL use approved integration (embedded BrowserView / external viewer); no arbitrary URLs — allowlist per UI_AND_DESIGN_PARITY.md / security review. |
| REQ-DESK-FR-124 | Reporting: draft / preliminary / final / addendum report states; signing typically online with non-repudiation server-side; offline MAY retain draft text locally with clear “not released” status. |
| REQ-DESK-FR-125 | Peer review / teaching / distribution: online-first; no silent publish offline. |
| REQ-DESK-FR-126 | DICOM / large payloads: streaming and WADO/DICOMweb remain network-bound; desktop SHALL support progress, cancel, and disk cache limits for local viewer artifacts. |
| REQ-DESK-FR-127 | Role separation: technologist, radiologist, resident, clerk views SHALL map to permissions; report signing gated by role + license. |
2. Non-functional requirements
| ID | Requirement |
|---|
| REQ-DESK-NFR-001 | Renderer SHALL use virtualized lists for long clinical tables; avoid unbounded DOM growth. |
| REQ-DESK-NFR-002 | Main thread SQLite queries SHALL be bounded (pagination, indexes); heavy work in worker threads where needed. |
| REQ-DESK-NFR-003 | Sync bursts SHALL not freeze UI — progress in renderer via IPC events. |
2.2 Security and privacy
| ID | Requirement |
|---|
| REQ-DESK-NFR-010 | PHI at rest: encrypted SQLite or file-level encryption per COMPLIANCE_SECURITY.md and TECHNICAL_REQUIREMENTS.md. |
| REQ-DESK-NFR-011 | Secrets: no secrets in renderer bundle; OS secure storage for refresh tokens; preload-only bridge. |
| REQ-DESK-NFR-012 | CSP, contextIsolation, sandbox webPreferences per Electron security baseline. |
| REQ-DESK-NFR-013 | Logs: structured, PHI-minimized (identifiers not raw narrative) per platform logging standards. |
2.3 Audit logging
| ID | Requirement |
|---|
| REQ-DESK-NFR-020 | Local audit trail for device-side actions SHALL sync or reconcile with server audit where required; gaps SHALL be detectable in operations. |
| ID | Requirement |
|---|
| REQ-DESK-NFR-030 | CI SHALL build and smoke-test all targeted OSes; native modules (SQLite, keytar, ONNX) SHALL have documented rebuild steps per OS. |
| REQ-DESK-NFR-031 | Paths, sleep/wake, proxy SHALL be tested; corporate proxy support documented for HTTPS to Kong. |
2.5 Accessibility and UX
| ID | Requirement |
|---|
| REQ-DESK-NFR-040 | WCAG-oriented targets aligned with web (keyboard, focus, contrast); MUI + roving tabindex patterns for dense tables. |
| REQ-DESK-NFR-041 | Density: Cloudflare-inspired compact layout — see §5. |
2.6 Reliability and maintainability
| ID | Requirement |
|---|
| REQ-DESK-NFR-050 | Crash reporting (optional) SHALL be opt-in / tenant-controlled; no raw PHI in crash payloads. |
| REQ-DESK-NFR-051 | Feature flags SHALL allow kill-switch for AI and experimental sync without redeploying server. |
| REQ-DESK-NFR-052 | Optional modules (lab, pharmacy, imaging, pop health, etc.) SHOULD use route-level code splitting so that unlicensed tenants do not load large bundles for those modules; entitlement changes after login SHALL trigger re-evaluation without requiring app restart where feasible. |
2.7 Sync engine (conflict resolution, cursors, batching)
| ID | Requirement |
|---|
| REQ-DESK-NFR-060 | Per-aggregate ordering for queued mutations; no unbounded parallel posts that violate causality. |
| REQ-DESK-NFR-061 | Server cursors / sync tokens for incremental fetch SHALL be persisted per tenant and collection. |
| REQ-DESK-NFR-062 | Batching with payload size limits; resume after partial failure without duplicate application (idempotent server + client reconciliation). |
| REQ-DESK-NFR-063 | Conflict handling SHALL be explicit (409, version fields); merge strategies per entity type documented in module specs. |
3. Integration requirements
| ID | Requirement |
|---|
| REQ-DESK-INT-001 | Kong: single HTTPS entry; routes per API_PATH_CONVENTIONS.md (/api/, /v1/, /fhir/R4/ as applicable). |
| REQ-DESK-INT-002 | Auth: OIDC/OAuth2 with PKCE for public desktop client; token refresh in main; logout clears session per policy. |
| REQ-DESK-INT-003 | Microservices: desktop is a client of public APIs only — no /internal/* paths from the app. |
| REQ-DESK-INT-004 | NATS: not used on desktop; backend services publish/consume events; desktop gets eventual consistency via sync and polling where designed. |
| REQ-DESK-INT-005 | Sync service endpoints: same REST resources as web; Idempotency-Key / clientMutationId as documented per service. |
| REQ-DESK-INT-006 | AI Gateway: Kong-exposed ai-orchestrator routes per AI_PLATFORM.md; rate limits and tenant headers as required. |
| REQ-DESK-INT-007 | FHIR (if used): read/write only through supported routes; desktop SHALL NOT bypass module validation. |
| REQ-DESK-INT-008 | Entitlements / capability map: the client SHALL consume a documented bootstrap or config-resolver surface (or equivalent aggregated API) that returns module license, feature flags, and effective permissions for building REQ-DESK-FR-090; exact paths live in BACKEND_AND_SERVICE_MAP.md / IAM docs and MUST stay in sync with implementation. |
4. Data requirements
4.1 Local SQLite (offline)
| Topic | Requirement |
|---|
| Schema versioning | Migrations in main; version table; rollback strategy documented. |
| Entities | Read models (patients, appointments, cached results), drafts, outbox, sync cursors, device metadata (app version, last sync), optional local snapshot of capability map (license + permissions hash) for offline UX — must refresh on reconnect; server remains authoritative. |
| Indexes | Required for tenant-scoped queries and foreign keys enabled. |
4.2 Mapping to backend Postgres
| Topic | Requirement |
|---|
| Ownership | Server owns canonical ids; client maps local temp ids to server ids on success responses. |
| No direct Postgres | Desktop never connects to Postgres; only HTTPS APIs. |
4.3 Change tracking
| Topic | Requirement |
|---|
| Outbox rows | Status machine: pending → syncing → completed / failed / conflict. |
| Tombstones / deletes | Propagate per module rules; soft delete vs hard per API. |
4.4 Encryption at rest
| Topic | Requirement |
|---|
| Keys | Derived from OS secure storage + tenant salt where specified in TECHNICAL_REQUIREMENTS. |
| Wipe | On logout or remote wipe command if platform supports — document. |
4.5 Data retention (local)
| Topic | Requirement |
|---|
| Retention | Configurable max cache age / max disk for PHI; purge on logout option. |
| Backups | User/OS backup tools MAY copy DB — mitigate via encryption at rest. |
5. UI/UX requirements (Electron + React)
5.1 Visual and navigation baseline
| ID | Requirement |
|---|
| REQ-DESK-UX-001 | Visual parity with apps/ehr-web (Berry template, MUI) per UI_AND_DESIGN_PARITY.md. |
| REQ-DESK-UX-002 | Cloudflare-inspired compact UI: increased data density, tight spacing scale, clear hierarchy, sticky headers for grids. |
| REQ-DESK-UX-003 | Navigation: persistent shell (sidebar + command palette optional), module routes, patient context chrome where the module requires it (EHR-centric); lab/pharmacy/imaging MAY use worklist-first chrome — same shell component family, different default layout per site profile. |
| REQ-DESK-UX-004 | Component library: MUI + shared packages; avoid one-off styling drift. |
| REQ-DESK-UX-005 | Theming: tenant branding via theme tokens from config-resolver; dark/light per user preference. |
| REQ-DESK-UX-006 | RTL/LTR and i18n per TECHNICAL_REQUIREMENTS.md TR-DSK-070–076. |
5.2 Modular UI, licensing, and permissions
| ID | Requirement |
|---|
| REQ-DESK-UX-007 | Capability-driven UI: every top-level module and major feature (e.g. “Inventory”, “QC”, “Report signing”) SHALL resolve from the same capability map as REQ-DESK-FR-090 — no hard-coded role checks scattered in JSX beyond thin wrappers. |
| REQ-DESK-UX-008 | Hide vs disable: Unlicensed features SHOULD be hidden from primary nav; licensed but forbidden features MAY show as disabled with tooltip (“No permission” / “Contact admin”) — consistent copy per product glossary. |
| REQ-DESK-UX-009 | Empty states: when a module is valid for the tenant but empty (no orders), SHALL show operational empty states distinct from unlicensed or forbidden states. |
| REQ-DESK-UX-010 | Settings / About: SHALL display effective license SKU summary (non-secret) and app version for help desk correlation; not a substitute for server enforcement. |
6. Deployment and update requirements
| ID | Requirement |
|---|
| REQ-DESK-DEP-001 | Signed installers; auto-update verifies signatures (TECHNICAL_REQUIREMENTS.md TR-DSK-050–051). |
| REQ-DESK-DEP-002 | Versioning: semver for app; minimum API version compatibility matrix with Kong/services. |
| REQ-DESK-DEP-003 | Local DB migrations: blocking migration UI on breaking changes; backup before migrate where feasible. |
| REQ-DESK-DEP-004 | Channels: beta/stable (and tenant-specific pinning if required). |
7. Acceptance criteria (Jira-ready)
7.1 Per module (representative Gherkin)
Feature: EHR offline charting
Scenario: Draft note saved without network
Given connectivity to Kong is unavailable
When the clinician saves a note in an offline-capable encounter
Then the note is stored in SQLite
And the outbox shows a pending sync operation
And the UI shows offline status
Feature: Admin online-only
Given administrative mutation APIs require live server
When the user attempts a tenant role change offline
Then the action is blocked or queued per explicit admin policy
And an explanation is shown
7.2 Offline-first behavior
Feature: No silent overwrite
Given a conflict response from the server
When the user opens the conflict resolution UI
Then regulated PHI is not discarded without an explicit user choice
7.3 Sync engine
Feature: Idempotent replay
Given a previously failed mutation with the same clientMutationId
When sync retries after connectivity returns
Then the server does not create duplicate clinical facts
And local state matches server reconciliation
7.4 AI features
Feature: Controlled AI path
Given cloud AI is enabled for the tenant
When the user requests a summary
Then the request goes to Kong ai-orchestrator with Bearer JWT
And no third-party API key is present in the renderer bundle
Feature: Local ONNX guardrails
Given local inference is enabled by policy
When ONNX runs in main or a worker
Then the renderer receives only redacted or policy-approved fields
And record updates require explicit user acceptance
7.5 Modular shell, license, and permissions
Feature: Unlicensed module hidden
Given the tenant license does not include the Pharmacy module
When the user opens the application shell
Then Pharmacy is not shown in primary navigation
And Pharmacy routes are not registered in the router map
Feature: Licensed but forbidden
Given the Pharmacy module is licensed
But the user lacks pharmacy.dispense permission
When they open the Dispensing screen
Then controls are read-only or disabled per UX policy
And mutation attempts receive 403 from the server
Feature: Entitlement refresh
Given the user is logged in
When the administrator revokes a role in IAM
Then the next capability refresh or API call updates the UI
And previously visible actions disappear without a full reinstall
7.6 Laboratory, pharmacy, imaging (representative)
Feature: Lab collection queue
Given Laboratory is licensed and the user has collection permissions
When they open the lab worklist
Then orders appear with priority and collection status
And offline behavior follows REQ-DESK-FR-106
Feature: Pharmacy verification gate
Given Pharmacy is licensed
When a technician completes a fill
Then pharmacist verification is required before release per policy
And the server rejects bypass if verification is skipped
Feature: Imaging report draft
Given Imaging is licensed
When the network is unavailable
Then report draft text may be saved locally with not-released status
And signing is blocked until online per policy
8. Traceability and backlog
- Epic split suggestion: (1) Shell + auth + IPC + capability map (license ⊕ RBAC ⊕ policy), (2) SQLite + outbox + sync, (3) EHR core vertical slice, (4) Laboratory worklist/collection/accession slice, (5) Pharmacy queue/dispense/inventory slice, (6) Imaging worklist/reporting + viewer integration, (7) Documents + OCR, (8) Billing + cross-module charge capture, (9) Reporting/pop health, (10) AI cloud + local, (11) Hardening + a11y + perf + lazy bundles.
- Module depth: For each REQ-DESK-FR-0xx, create stories that reference the module’s
SPEC.md / TECHNICAL_REQUIREMENTS.md for clinical validation and API ids.
- Normative duplicates: Detailed TR tables in TECHNICAL_REQUIREMENTS.md and FR tables in SPEC.md remain authoritative for desktop-specific IDs (FR-DSK-, TR-DSK-); this document adds cross-module REQ-DESK-* traceability for program-level planning.
9. Document history
| Version | Date | Notes |
|---|
| 1.0 | 2026-04-13 | Initial Electron-tailored master requirements (from generic desktop spec template). |
| 1.1 | 2026-04-13 | Laboratory, pharmacy, imaging workflows; modular shell + licensing + RBAC; UX and NFR for lazy-loaded modules; acceptance criteria expanded. |