Patient Portal Service — AI Integration
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
1. Overview
The patient-portal-service exposes one AI capability to authenticated patients: a non-diagnostic navigation assistant. All AI calls are routed through ai-gateway-service (Tier A — patient-facing, non-diagnostic). No clinical reasoning or diagnostic inference is performed. PHI is not included in prompt payloads.
2. AI Calls Catalog
| # | Feature | Purpose | Tier | HITL | FR Ref |
|---|---|---|---|---|---|
| 1 | Portal Navigation Assistant | Help patients find the right section of the portal (e.g., "Where are my results?"). Non-diagnostic, navigation-only. | A | No HITL for navigation replies; moderation filter blocks disallowed content | FR-PORTAL-013 |
3. Integration Details
3.1 Portal Navigation Assistant
Endpoint called: POST /v1/ai/completions on ai-gateway-service
Feature flag: ai.patient-assistant must be enabled for the tenant. If disabled, /v1/portal/ai/navigate returns 403 FEATURE_NOT_ENABLED.
Prompt template name: portal_navigation_v1
Prompt construction rules:
- System prompt: role-scoped as "portal guide" — navigation only.
- User message: free-text patient input (max 500 chars; truncated otherwise).
- No PHI fields (name, DOB, patient ID, diagnosis) are injected into the prompt.
- The response is limited to navigation guidance and portal-feature explanations.
Moderation: ai-gateway-service applies its content moderation filter before returning the response. Any response flagged as diagnostic, prescriptive, or off-domain is suppressed and replaced with a fallback message: "I can only help you navigate the portal. For clinical questions, please contact your care team."
HITL policy: Not required for navigation replies. All requests and responses are logged via ai-gateway-service audit trail with accountId and anonymized session context.
AIProvenance record: Every navigation response includes a provenance field indicating model tier, prompt template version, and moderation status. This is surfaced in the API response but not stored in portal DB.
4. Constraints and Guardrails
| Guardrail | Description |
|---|---|
| No PHI in prompts | Patient name, ID, DOB, diagnosis, medication names are never included in AI prompts |
| Non-diagnostic boundary | System prompt explicitly prohibits clinical diagnosis, drug dosing, and treatment advice |
| Rate limit | Max 10 AI requests per portal session; enforced at the BFF layer |
| Audit | All AI interactions logged to ai-gateway-service audit stream |
| Tenant opt-in | Feature flag ai.patient-assistant required; disabled by default |
| Fallback | If ai-gateway-service is unavailable, /v1/portal/ai/navigate returns 503 gracefully without breaking core portal flows |
5. Future Scope
| Potential future capability | Notes |
|---|---|
| Appointment scheduling suggestion | Suggest available providers based on condition type — requires HITL and clinical review policy |
| Lab result plain-language summary | Patient-friendly result explanation — must remain strictly non-diagnostic; requires separate Tier A safety review |
| Prescription refill eligibility check | Require explicit physician-in-the-loop design before enabling |
All future AI features require ai-gateway-service Tier classification review and MoPH compliance sign-off before activation.