Build guide: patient mobile (React Native)
Version: 1.0
Date: 2026-03-31
Audience: Engineers and AI agents adding apps/ehr-patient-mobile to this monorepo.
1. Before writing code
Read in order:
- README.md (pack index)
- SPEC.md and TECHNICAL_REQUIREMENTS.md
- IMPLEMENTATION_ROADMAP.md
- BACKEND_AND_SERVICE_MAP.md
- AUTH_AND_SESSION.md, API_CLIENT_AND_KONG.md
- REGIONAL_PROFILE.md for i18n/RTL
- STANDARDS_ALIGNMENT.md
Platform-wide frontend index: docs/ehr-frontend-specs-index.md.
2. Monorepo placement
| Item | Value |
|---|---|
| Suggested app path | apps/ehr-patient-mobile |
| Workspace | Root pnpm-workspace.yaml — include the app when created |
| Task runner | Follow Turbo patterns used by other apps/* |
Add the package with private: true and packageManager/engines consistent with sibling apps (ARCHITECTURE_AND_MONOREPO.md).
3. Environment variables (illustrative)
Define in .env.example only—never commit secrets. For Expo, never put secrets in EXPO_PUBLIC_*.
| Variable | Purpose |
|---|---|
KONG_PUBLIC_BASE_URL | HTTPS origin for Kong (e.g. dev gateway) |
OIDC_ISSUER | Keycloak (or IdP) realm issuer URL |
OIDC_CLIENT_ID | Public client for mobile (PKCE) |
OIDC_REDIRECT_URI | Custom scheme (com.ghasi.patient://...) or HTTPS app link |
Exact names MUST match deployment and infra/keycloak realm configuration when a dedicated mobile client is registered.
4. Keycloak / IAM (mobile client)
- Register a public OIDC client for the app with PKCE enabled (S256).
- Add valid redirect URIs and (if used) post-logout redirect URIs for the app scheme / universal links.
- Realm reference: ghasi-realm.json — coordinate with platform team before editing; document new client IDs in deployment runbooks, not in committed secrets.
5. Scripts (illustrative)
| Script | Purpose |
|---|---|
lint | ESLint |
typecheck | tsc --noEmit |
test | Jest / Vitest unit tests |
e2e | Maestro / Detox (optional CI) |
Align with TESTING_STANDARDS.md when wiring CI.
6. Definition of Done (per milestone)
- Security: No refresh tokens in AsyncStorage; no PHI in default logs (OBSERVABILITY_AND_PRIVACY.md).
- API: Only Kong-public paths; no
/internal/*(API_PATH_CONVENTIONS.md). - i18n: At least one RTL locale smoke-tested (I18N_AND_RTL.md).
- Quality: Lint + typecheck green; critical path E2E or manual test script documented (TESTING_AND_RELEASE.md).
7. Related desktop pattern
For monorepo discipline only, compare with desktop-electron/AI_AGENT_BUILD_GUIDE.md (different persona, no SQLite/outbox for patient MVP).