Ghasi-eHealth Mobile App — specification pack
This folder defines implementation guidance for @ghasi/ehr-mobile — the single React Native mobile application that serves every mobile persona on the Ghasi-eHealth platform.
The app is one bundle, one store listing per platform, one codebase, surfacing role-based navigation and feature gating so the same binary serves:
| Persona | Role |
|---|---|
| Patient | Self-care — own appointments, results, messaging, meds |
| Caregiver | Proxy care for family or assigned subjects (per consent grant) |
| Guardian | Legal proxy for minors or dependants |
| CHW / Local health worker | Community health — household registry, visits, commodity dispensing, offline-heavy field capture |
See PERSONAS_AND_ROLES.md for the full persona model, capability matrix, and gating.
Authority and reading order
| Rule | Detail |
|---|---|
| Specs vs docs | When ambiguous, specs/ wins over docs/. |
| Normative product behaviour (patient workflows) | ../../modules/patient-portal/ (SPEC, TECHNICAL_REQUIREMENTS, patient-portal-requirements-doc). |
| Normative product behaviour (CHW workflows) | specs/modules/community-health/ (where licensed). |
| Normative product behaviour (proxy care) | specs/modules/consent-service/ + specs/modules/patient-portal/ proxy sections. |
| Theme, tokens, RTL, motion | ../../common/THEME.md — canonical source across all surfaces. |
| Standards alignment | STANDARDS_ALIGNMENT.md — SMART/PKCE, FHIR/IPS, privacy, WCAG. |
| Traceability | TRACEABILITY_MATRIX.md + per-module matrices. |
| Backend gaps & roadmap | BACKEND_GAPS_AND_ROADMAP.md. |
| Platform cross-cutting | REGIONAL_PROFILE.md, API_PATH_CONVENTIONS.md, COMPLIANCE_SECURITY.md. |
| Frontend index | docs/ehr-frontend-specs-index.md. |
Start here (scaffolding and delivery):
- BUILD_GUIDE.md — monorepo, env, DoD, IAM pointers
- IMPLEMENTATION_ROADMAP.md — phased delivery and exit criteria
- BACKEND_AND_SERVICE_MAP.md — feature → service → Kong → screen
Deep-dive read order:
- ARCHITECTURE_AND_MONOREPO.md
- PERSONAS_AND_ROLES.md
- AUTH_AND_SESSION.md
- API_CLIENT_AND_KONG.md
- I18N_AND_RTL.md
- UI_UX_PATTERNS.md
- SCREENS_AND_NAVIGATION.md
- PUSH_AND_DEEP_LINKS.md
- OFFLINE_AND_CACHING.md
- OBSERVABILITY_AND_PRIVACY.md
- TESTING_AND_RELEASE.md
Pattern reference (desktop monorepo): desktop-electron/AI_AGENT_BUILD_GUIDE.md.
Audience
Engineers and AI agents implementing the unified mobile client across patient, caregiver, guardian, and CHW personas. Normative clinical and product requirements remain in each module spec; this pack describes how to build the React Native app against Kong-public APIs and OIDC, share one theme with desktop + web, and surface the correct persona-scoped experience.
Relationship to other surfaces
| Surface | Spec pointer |
|---|---|
| Single theme / design system | ../../common/THEME.md — MUI + Tailwind (desktop/web), React Native Paper + NativeWind (mobile), shared tokens, per-tenant overrides, Motion + Reanimated. |
| Web patient portal | apps/patient-portal — Next.js BFF. Same FR/NFR family as patient-portal SPEC; browser uses cookie + server-forwarded tokens. |
| Shared API types | @ghasi/patient-portal-client — mobile and web use the same DTO shapes. |
Clinician desktop (ehr-desktop) | Different surface class; reuse only Kong base URL and theme tokens (API_PATH_CONVENTIONS.md, ../../common/THEME.md). |
| Clinician web (future) | Same pattern — consumes the same theme tokens. |
Architecture overview
Mobile, web, and desktop SHALL share the same authorisation model (SPEC.md §2, TECHNICAL_REQUIREMENTS.md §1) and the same theme pipeline (../../common/THEME.md).
Document index
| Document | Purpose |
|---|---|
| BUILD_GUIDE.md | Monorepo setup, env, CI, Definition of Done |
| IMPLEMENTATION_ROADMAP.md | Phases 0–5, exit criteria, backend dependencies |
| BACKEND_AND_SERVICE_MAP.md | Feature → module → service → Kong → mobile screen |
| PERSONAS_AND_ROLES.md | Persona model, capability matrix, proxy access, CHW specifics |
| STANDARDS_ALIGNMENT.md | Mobile security / a11y checklist vs international patterns |
| OBSERVABILITY_AND_PRIVACY.md | Telemetry, crashes, analytics without PHI |
| ARCHITECTURE_AND_MONOREPO.md | apps/ehr-mobile, Expo vs bare, stack, licensing, persona feature bundles |
| AUTH_AND_SESSION.md | OIDC + PKCE, secure storage, biometrics, proxy context |
| API_CLIENT_AND_KONG.md | /v1/* routes, errors |
| I18N_AND_RTL.md | Locales, RTL, calendars, numbers — see also ../../common/THEME.md §10 |
| UI_UX_PATTERNS.md | Per-persona UX patterns, a11y |
| SCREENS_AND_NAVIGATION.md | Tabs, stacks, persona-scoped navigation, licensing gates |
| PUSH_AND_DEEP_LINKS.md | FCM/APNs, universal links, persona-aware notification routing |
| OFFLINE_AND_CACHING.md | Cache policy per persona (CHW offline-heavy, consumer lightweight) |
| TESTING_AND_RELEASE.md | Tests, store checklist |
Application path
Implementation package: apps/ehr-mobile (@ghasi/ehr-mobile, private; aligns with root pnpm-workspace.yaml and Turbo). Normative requirements remain in this specs/ pack plus the relevant module specs (patient-portal, community-health, consent-service).