Architecture and monorepo placement
References: SPEC.md §2, TECHNICAL_REQUIREMENTS.md, API_PATH_CONVENTIONS.md.
1. Monorepo location
| Item | Recommendation |
|---|---|
| Package path | apps/ehr-patient-mobile |
| Visibility | private: true in package.json |
| Workspace | Root pnpm-workspace.yaml — include apps/ehr-patient-mobile when created |
| Task runner | Follow existing Turbo patterns in sibling apps/* |
Keep shared TypeScript types (DTOs mirroring API JSON) in a small package under packages/ only if the web patient portal or BFF already publishes contracts; otherwise colocate src/api/types in the app and align manually with patient-portal-requirements-doc.md §6.
2. React Native baseline: Expo vs bare workflow
| Approach | When to use |
|---|---|
| Expo (recommended default) | Faster delivery for patient features: secure storage plugins, push notifications, universal links, OTA updates (policy permitting), dev client for native modules. Use development builds when you need custom native code not in Expo Go. |
| Bare React Native | Only if product mandates a fully custom native shell from day one; you then own push, linking, and secure storage integration. |
Document the chosen SDK version in the app README when implemented; pin versions for reproducible builds.
3. Core libraries (illustrative)
These are not normative requirements but a sensible default stack:
| Concern | Options |
|---|---|
| Language | TypeScript (strict) |
| Navigation | React Navigation 6+ (native stack + bottom tabs) |
| Server state | TanStack Query (React Query) for cache, retries, stale-while-revalidate |
| Forms | React Hook Form + Zod (or platform validation) for booking and demographics |
| HTTP | fetch with a thin wrapper for auth headers and error mapping (API_CLIENT_AND_KONG.md) |
| Secure storage | Expo SecureStore or react-native-keychain |
Avoid embedding third-party analytics keys for PHI-heavy screens without DPA and tenant policy (COMPLIANCE_SECURITY.md).
4. Feature configuration and licensing
Patient-visible modules (messaging, billing, telehealth, deep record types) SHALL be gated by tenant configuration and licensing (SPEC.md FR-PORT-011..012, MODULE_SHARED_STANDARDS.md §1).
Implementation pattern:
- After login, resolve portal capabilities from a small set of server-driven flags (e.g. from
/v1/portal/meextension or config endpoint—finalize with backend). Do not hardcode feature availability per build flavor for clinical safety; use remote config only for non-clinical UX experiments if approved.
5. Environment configuration
Define non-secret configuration via env at build time (e.g. EXPO_PUBLIC_* only for non-sensitive endpoints if using Expo—never put secrets in EXPO_PUBLIC_).
Illustrative variables (names must match deployment):
| Variable | Purpose |
|---|---|
KONG_PUBLIC_BASE_URL | HTTPS origin for the API gateway |
OIDC_ISSUER | Identity provider issuer URL |
OIDC_CLIENT_ID | Public OIDC client (PKCE) |
OIDC_REDIRECT_* | App scheme or universal link callback |
See AUTH_AND_SESSION.md for token handling.
6. AI features
If the product exposes AI-assisted education to patients, calls MUST go only through Kong /v1/ai/* per SPEC.md AI subsection—no vendor keys in the client.