09 — Frontend Workflows and User Journeys
Status: populated Last updated: 2026-04-18 Companion: 07 epics-and-user-stories · 08 frontend-design-guidelines · 16 offline-first · 13 security-compliance-tenancy
This document enumerates the canonical end-to-end UI workflows across the seven Ghasi-eHealth surfaces. Each workflow declares: actors, role-based UI variants, services touched, state model, offline fallbacks, and links to the J-NN journey in 07 §4.
1. Critical-path workflow map
| ID | Workflow | Primary surface | Journey link | E2E gate |
|---|---|---|---|---|
| W-01 | Clinician sign-in → patient list → chart → order → sign | Clinician Web | J-03 | Yes |
| W-02 | Registration desk intake (new patient, returning patient, emergency) | Registration Station | J-02, J-17 | Yes |
| W-03 | Scheduling — book, reschedule, cancel, waitlist, overbook | Scheduling view in Clinician Web + Patient Portal | J-02, J-10 | Yes |
| W-04 | Pharmacy / dispense — queue, verify, counsel, label, dispense | Pharmacy Portal | J-04, J-18 | Yes |
| W-05 | Lab workflow — accession, specimen, instrument feed, verify, release | Lab Portal | J-05, J-12 | Yes |
| W-06 | Patient portal — account, appointments, results, messages, demographic update | Patient Portal Web + Mobile | J-09, J-10, J-12, J-21 | Yes |
| W-07 | Virtual visit — pre-visit checklist → call → note → bill | Virtual Care Room | J-08 | Yes |
| W-08 | Field immunization clinic (full offline) | Provider Mobile | J-07, J-25 | Yes |
| W-09 | Radiology report drafting | Clinician Web (radiologist persona) | J-06 | Yes |
| W-10 | Break-glass emergency access | Clinician Web (any) | J-17 | Yes |
2. Cross-workflow conventions
- Every workflow logs analytics events to the observability pipeline (12 observability-telemetry).
- Every workflow honors LTR + RTL; visual regression suite covers both.
- Every workflow has a documented offline fallback (or explicitly states "online-only" with rationale).
- Every PHI read/write emits an
audit.*event before the user-facing response completes. - Every AI-assisted step surfaces provenance and a HITL signature step.
W-01 — Clinician clinical workflow
Actors: Physician, nurse, resident, charge nurse, midlevel. Surfaces: Clinician Web (primary), Provider Mobile (read-only chart + quick note). Services touched: identity · patient-chart · orders · medication · terminology · laboratory · radiology · communication · audit · ai-gateway (optional scribe).
State diagram
Step-by-step
| # | Step | Acceptance | Offline fallback | AI |
|---|---|---|---|---|
| 1 | Sign in via Keycloak (OIDC) | JWT + device-bind on trusted workstations | Desktop station: last-good token cached 8 h | — |
| 2 | Land on patient list (assigned + ward) | Sortable by triage / last-vitals / stat-orders | Cached worklist (last 24 h) | Cohort triage hint (opt-in) |
| 3 | Open chart | Allergy banner, active problems, active meds, last vitals in < 2.5 s p75 | Read-only chart from cache | — |
| 4 | Review longitudinal data | Timeline widget scrubbing encounters | Read-only | Summary card |
| 5 | Order entry | Unified CPOE card with DDI + allergy + duplicate check | Queued locally, sealed; released on reconnect | Order set suggest |
| 6 | Sign orders | PIN / WebAuthn step-up | Queued with counter-signature | — |
| 7 | Document note | Rich-text + structured blocks; template library | Drafted locally | Scribe (see W-07) |
| 8 | Sign note | Attested; immutable afterward | Queued | — |
Role-based variants
| Role | Variant |
|---|---|
| Physician | Full CPOE, full note authoring, sign authority |
| Resident | CPOE with co-signing required from attending |
| Nurse | No CPOE; vitals entry, med admin rec, structured notes |
| Charge nurse | Ward-level census view; assignment UI |
| Midlevel | Scope-limited CPOE (no controlled substances unless credentialed) |
Offline fallback
On desktop: queued writes held in SQLite outbox, visible in Sync Center. On Provider Mobile: read-only chart from Realm cache; new notes queued as append-only.
W-02 — Registration desk workflow
Actors: Registration clerk, triage nurse, cashier. Surfaces: Registration Station (Electron desktop, Windows / macOS / Linux). Services touched: registration · identity · patient-chart · scheduling · facility · insurance (claims) · document · communication · audit.
State diagram
Variants
| Scenario | Variant |
|---|---|
| New patient | Full demographics, consent, biometric capture (photo, ID scan), guardian if minor |
| Returning patient | Identity match (NID + DOB + phone) → confirm demographics → new encounter |
| Emergency walk-in | Skip scheduling; create "John/Jane Doe" stub; reconcile identity later |
| Outreach enrolment | Offline registration on mobile; sync reconciliation at return |
| Cross-facility transfer | Accept external identity via interop-service; MRN reconciliation UI |
Offline fallback
Full offline support. SQLite outbox persists all registrations. Identity match falls back to local index; "deferred match" state if server index unavailable. All PHI writes carry clientMutationId for idempotent replay on reconnect.
Key form affordances
- Name fields accept bidi text;
<bdi>isolates Latin drug names inside Dari sentences. - Date of birth: Solar Hijri + Gregorian picker; stored as ISO-8601.
- National ID (Tazkira) + biometric capture hooks.
- Consent: versioned policy text; signed; audit log.
W-03 — Scheduling workflow
Actors: Scheduler, clerk, clinician, patient (portal), nurse. Surfaces: Clinician Web (scheduling module), Patient Portal, Patient Mobile. Services touched: scheduling · provider-directory · facility · communication · patient-portal · audit.
Sub-workflows
| Sub | Description | Role variants |
|---|---|---|
| Book | Search slots by provider / specialty / location / date → confirm | Staff can overbook; patient cannot |
| Reschedule | Move an existing appointment with conflict check | Patient limited to 1 self-reschedule / appt |
| Cancel | With policy-driven confirmation + optional reason | — |
| Waitlist | Add to waitlist; auto-promote when slot opens | Opt-in by patient |
| Overbook | Staff-only; requires reason code | Audit event mandatory |
| Resource booking | Book facility resource (bed, exam room, infusion chair) | Staff only |
State (per appointment)
Offline fallback
Read-only slot list from cached facility schedule. Booking is online-only (server must validate slot availability authoritatively). On reconnect, stale views refresh via NATS-driven cache invalidation.
W-04 — Pharmacy workflow
Actors: Pharmacist, pharmacy tech, dispenser, cashier. Surfaces: Pharmacy Portal (Next.js web). Services touched: medication · ghasi-eprescribing-gateway · orders · terminology · billing · audit.
Queue → verify → counsel → dispense flow
Step variants
| Step | Notes |
|---|---|
| Queue | Poll / subscribe to eprescribing.gateway.medication_request.* |
| Verify | Pharmacist checks DDI, allergy, therapeutic duplication; may substitute with prescriber approval |
| Label | Print specimen/dose label with bilingual instructions |
| Counsel | Patient education; bilingual material; record counseling event |
| Dispense | Stock decrement, controlled-substance check, MedicationDispense back through gateway |
| Reject | Reason code; notify prescriber via communication-service |
Offline fallback
Partial — read queue from last-sync cache; writes queued. Controlled-substance dispensing is online-only (requires canonical stock authority).
W-05 — Lab workflow
Actors: Lab tech, pathologist, accessioning clerk. Surfaces: Lab Portal (Next.js). Services touched: laboratory · orders · interop (instrument feeds, HL7 v2) · patient-chart · communication · audit.
Flow
Role variants
| Role | Capabilities |
|---|---|
| Accessioning clerk | Receive, label, route to worklist |
| Lab tech | Run, enter manual results, flag critical |
| Pathologist | Verify, sign, release |
| Supervisor | Reopen, correct, delta-release |
Offline fallback
Instrument bench can operate offline via local HL7 buffering in the interop-service adapter. Result release to patients is online-only (consent gating).
W-06 — Patient portal workflow
Actors: Patient, guardian, caregiver. Surfaces: Patient Portal Web + Patient Mobile. Services touched: identity (portal realm) · patient-portal · scheduling · patient-chart (read) · laboratory (released results) · communication · audit.
Sub-workflows
| Sub | Steps |
|---|---|
| Account | Sign-up (OTP + phone verify) → identity match → link to chart |
| Appointments | View, book, reschedule, cancel |
| Results | Released-only; annotated with clinician message if any |
| Messages | Secure thread with care team (async, non-urgent) |
| Demographics | Patient-initiated update → clinic review queue |
| Consent & DSAR | Consent change, data export, deletion (DPO-mediated) |
Offline UX
Mobile: read-only cache of last-seen chart, results, and appointments. No writes queued from portal (by policy — patient writes require online confirmation to prevent impersonation replay attacks).
Role variants
| Persona | Variant |
|---|---|
| Patient | Full self-service |
| Guardian (minor) | Delegated access; minor-rules (no sensitive categories until age of majority) |
| Caregiver (delegated) | Patient-granted scoped access; time-boxed |
W-07 — Virtual visit workflow
Actors: Clinician, patient, optional interpreter. Surfaces: Virtual Care Room (Next.js + Jitsi SDK). Services touched: virtual-care · communication · identity · patient-chart · billing · ai-gateway (scribe) · audit.
Flow
Pre-visit checklist
- Tech check — camera, mic, network speed.
- Consent to telemedicine (versioned policy).
- Reason for visit and vital self-entry (patient).
- Pharmacy preferences confirmed.
Offline fallback
Online-only. If connection degrades, session FSM transitions to RECONNECTING; session auto-ends after TIMEOUT with state preserved for resumption within 15 min.
W-08 — Field immunization clinic (full offline)
Actors: Outreach nurse, team lead. Surfaces: Provider Mobile (Expo + Realm). Services touched: immunizations · registration · patient-chart · interop · population-health · audit.
Flow
Offline model
- Full offline capability — patient identification (NID scan, biometric), dose administration, consent, AEFI recording.
- Local Realm DB; append-only events; MAC-signed batches.
- Conflict policy per aggregate:
Patient— server-authoritative (MPI);Immunization— append-only;Consent— LWW + diff (manual resolution on re-enrol). - Bundle re-sync in ≤ 60 s for ≤ 10 MB per device after reconnect.
HMIS linkage
Verified doses project into population-health-service daily aggregates; monthly indicator exports to MoPH via interop-service.
W-09 — Radiology report drafting
Actors: Radiologist, resident, technologist. Surfaces: Clinician Web with radiologist persona layout + viewer launch (external DICOM viewer). Services touched: radiology · orders · patient-chart · document · ai-gateway · audit.
Flow
| # | Step |
|---|---|
| 1 | Pick worklist entry by modality / priority |
| 2 | Launch viewer (signed URL; DICOM studies) |
| 3 | AI draft summary streams into report pane |
| 4 | Radiologist edits, adds impression, signs |
| 5 | Report released → chart + communication to ordering clinician |
AI provenance
Every AI-drafted report section carries provenance badge; radiologist signature = human attestation; reports without a human signature cannot release.
W-10 — Break-glass workflow
Actors: Clinician in emergency. Surfaces: Clinician Web. Services touched: identity · patient-chart · audit.
Flow
- Clinician attempts access outside ABAC scope (e.g., patient on another ward).
- Access-policy denies; UI offers "Break-glass" with reason codes.
- Clinician confirms with step-up (PIN / WebAuthn).
- Access granted for time-boxed window (default 4 h).
- Elevated audit event fires (
audit.breakglass.invoked). - Compliance review queue receives the event; manual review within 24 h.
Offline behaviour
On desktop with last-good ABAC decisions cached: break-glass decisions are queued; audit event signed locally; flushed on reconnect with tamper detection.
3. Notifications and messaging
Every workflow emits notifications through communication-service:
| Trigger | Channel default | Urgency | Template |
|---|---|---|---|
| Appointment booked | SMS + portal inbox | normal | appt.booked |
| Appointment tomorrow | SMS + push | normal | appt.reminder.24h |
| Result released | portal inbox (SMS if opted) | normal | result.released |
| Critical result | call + SMS + push | critical | result.critical |
| Rx ready | SMS | normal | rx.ready |
| DSAR export | portal download link | normal | dsar.ready |
PHI never leaks into push / SMS payloads — templates are generic; detailed content accessed only in authenticated surface.
4. Error and exception patterns
- Validation errors — inline,
aria-describedbytie; surface stable error code; never raw stack. - ABAC denials — neutral message + optional break-glass invitation (W-10).
- Licensing denials — inline with "contact administrator" affordance.
- Network loss — Sync pill flips to
offline; in-flight mutations preserved; user informed non-blockingly. - AI refusal — clear, neutral; rephrase invitation.
- Audit write failure — the entire write is rolled back; user sees "Try again".
5. Why this set of workflows
These ten workflows cover every licensed module and every persona in the platform. Each has an E2E gate because they represent the workflows where regressions would be noticed first by clinical staff and where failure has real-world patient-safety implications. Offline fallbacks follow 16 offline-first invariants; AI affordances follow 08 design guidelines §10. Role-based UI variants reuse the same component tree — divergence is carried in Zustand role selectors, not in duplicate screens.
6. Open questions
- Final shape of the pharmacy counseling capture on mobile pharmacies in field deployments.
- Whether virtual care should offer a peer-to-peer fallback (without media server) for low-bandwidth scenarios.