Backend and service map — patient mobile
Version: 1.0
Date: 2026-03-31
Maps patient mobile features to module specs, services, Kong routes, and typical mobile screens. Persona: patient only (not clinician desktop).
Gateway: Kong routes /v1/portal → patient-portal-api (kong.yml patient-portal-root); other /v1/* routes per service. Clients MUST NOT call /internal/* (API_PATH_CONVENTIONS.md).
Patient authorization (important)
Several scheduling and provider-directory routes are implemented today with staff-oriented role guards (DOCTOR, NURSE, ADMIN, etc.). Patient JWTs may receive 403 on GET /v1/practitioners, POST /v1/appointments, PUT .../cancel, and related flows until platform work completes. GET /v1/appointments?patientId= must enforce patient binding to the caller (no IDOR). The canonical gap list, security notes, and phased roadmap (P0–P5) are in BACKEND_GAPS_AND_ROADMAP.md. Do not assume “route exists in Kong” means “works for PATIENT” without checking that doc.
1. Core platform
| Concern | Module / doc | Service (illustrative) | Kong prefix / notes |
|---|---|---|---|
Portal accounts, /me, demographics requests, portal appointments listing | patient-portal/SPEC.md | apps/services/patient-portal-api | /v1/portal |
| Practitioner search | scheduling / discovery | provider-directory | /v1/practitioners (per patient-portal-requirements-doc §6) |
| Schedules, slots | scheduling | scheduling | /v1/schedules, slots |
| Book/cancel appointment | scheduling | scheduling | /v1/appointments |
| Released results | results | results + portal BFF policy | /v1/portal/results (when implemented) |
| Secure messaging | digital-communication, NOTIFICATIONS_PLATFORM | digital-communication | Staff: /v1/digital-communication/messaging/* (API_DOCS); patient portal BFF /v1/portal/messages when licensed (interop API_DOCS §4.4) |
| Billing | billing / financial modules | TBD | When FR-PORT-012 enabled |
2. Feature to mobile screen (typical)
| Feature | Module FR | Mobile screens | API surface (patient-intent; verify roles) |
|---|---|---|---|
| Login / session | FR-PORT-001 | Auth stack, settings | OIDC; then /v1/portal/me |
| Home / summary | FR-PORT-003 | Home tab | GET /v1/portal/record/summary |
| Find provider | FR-PP-002..003 (product doc) | Search, map | GET /v1/practitioners (staff-guarded today; see BACKEND_GAPS_AND_ROADMAP) |
| Book visit | FR-PORT-004 | Booking wizard | GET /v1/schedules; book via portal request or patient-scoped scheduling (staff POST /v1/appointments today — BACKEND_GAPS_AND_ROADMAP) |
| Results | FR-PORT-005 | Records tab, detail | GET /v1/results with PATIENT JWT + patient_id claim (released-only for patients); align with web BFF /api/clinical/results |
| Demographics update | FR-PORT-006 | Profile / forms | Portal demographics endpoints |
| Messages | FR-PORT-011 | Messages tab | Messaging module API (when exposed) |
| Pay / balance | FR-PORT-012 | Billing / More | Billing integration |
| Proxy | FR-PORT-008 | Patient switcher | TBD proxy APIs |
| Export | FR-PORT-010 | Profile / privacy | TBD export endpoints |
| Telehealth join | FR-PORT-009 | Schedule / deep link | Scheduling + telehealth metadata |
3. Traceability and backlog
Several patient-facing flows remain partial or backlog on the server (TRACEABILITY_MATRIX.md). Authorization and booking gaps are tracked in BACKEND_GAPS_AND_ROADMAP.md. Mobile implementation MUST align with both—do not assume APIs exist or are patient-eligible until verified.
4. FHIR (optional direct access)
If the product exposes FHIR to the mobile app through Kong (/fhir/R4/...), treat it as a constrained read surface per FHIR_FIRST_STANDARD.md and SPEC.md §7—same policy gates as REST.
5. Related maps
- Clinician desktop: desktop-electron/BACKEND_AND_SERVICE_MAP.md (different persona).