Patient Portal

Trust tier roll-up

RBAC matrix (IC 0–100 scale)

* Proxy level is context-dependent: the base level is 10, but proxy access is further gated by the SensitiveClassGating consent flags and the authorization-chain trace. A proxy without consent for a sensitive class cannot view data in that class even at level 10.

FK Relationship Diagram

erDiagram
    Patient ||--o{ PortalMessage : "sends/receives"
    User ||--o{ PortalMessage : "SenderUserID"
    User ||--o{ PortalMessage : "RecipientUserID"
    PatientDocument ||--o{ PortalMessage : "AttachedDocumentID"
    Patient ||--o{ PatientDocument : "owns"
    Encounter ||--o{ PatientDocument : "attached to"
    Patient ||--o{ Payment : "pays"
    Encounter ||--o{ Payment : "for"
    PatientStatement ||--o{ Payment : "StatementID"
    Patient ||--o{ SensitiveClassGating : "consents"
    SensitiveClassGating ||..|| PatientDocument : "gates access"
    

Message Thread State Machine

stateDiagram-v2
    [*] --> Draft
    Draft --> Sent : Patient or staff sends
    Sent --> Read : Recipient opens
    Read --> Replied : Recipient responds
    Replied --> Read : Original sender reads reply
    Read --> Closed : Manager closes thread
    Replied --> Closed : Manager closes thread
    Sent --> Escalated : SLA breached
    Escalated --> Read : Recipient opens after escalation
    

Functional Requirements

1. P0 The system SHALL allow patients to send secure messages to their care team and receive threaded responses.
2. P0 The system SHALL enforce sensitive-class consent gating: documents marked IsSensitive=true are hidden from any user/proxy until the matching SensitiveClassGating record shows IsConsented=true.
3. P0 The system SHALL allow patients to grant or revoke consent per sensitive class (BehavioralHealth, SubstanceUse, HIV, ReproductiveHealth) at any time.
4. P0 The system SHALL process online payments (credit/debit/ACH) via the patient portal with PCI-DSS compliant tokenization (no card numbers stored).
5. P0 The system SHALL support family/proxy access gated by per-class ProxyAccessAllowed flag on SensitiveClassGating.
6. P1 The system SHALL track message SLA (ResponseSLAHours) and trigger escalation workflows when deadlines are breached.
7. P1 The system SHALL allow patients to upload documents (insurance cards, forms, images) with file-type validation and virus scanning.
8. P1 The system SHALL display patient statements and support partial payments and payment plans.
9. P1 The system SHALL allow staff to attach portal messages to an encounter record.
10. P1 The system SHALL support message categorization (Clinical, Billing, Administrative) for routing.
11. P1 The system SHALL allow billers to create and adjust payment records for copays and balances.
12. P1 The system SHALL allow managers to void or refund payments with audit trail.
13. P2 The system SHALL support cross-org document sharing when SharingWithOtherOrgsAllowed=true on the relevant SensitiveClassGating record.
14. P2 The system SHALL support payment receipt generation and email delivery.
15. P2 The system SHALL provide read-receipt tracking for portal messages.
16. P2 The system SHALL allow patients to download their complete document history as a ZIP export.

Non-Functional Requirements

• Availability: Patient portal 99.9% uptime; maintenance windows outside 6AM-10PM patient-local-time.
• Latency: Message send/receive round-trip under 2 seconds (95th percentile).
• Security: All documents encrypted at rest (AES-256); SAS-token gated blob access with 15-minute expiry.
• PCI-DSS: Payment processing uses tokenized card references only; no PAN stored in application database.
• File Upload: Maximum 25 MB per file; allowed MIME types: PDF, JPEG, PNG, TIFF, HEIC; virus scan before storage.
• Consent Audit: Every consent change (grant/revoke) logged with actor, timestamp, IP; immutable audit trail.
• Accessibility: Portal UI meets WCAG 2.1 AA; screen-reader compatible messaging interface.
• SLA Monitoring: Escalation engine checks unread messages every 5 minutes; alert to manager when ResponseSLAHours exceeded.

icApplication Overrides

How the four Patient Portal AMI schemas turn into a live application: module-specific stack additions, override component bindings, a versioning worked example, environment cascade, and RBAC enforcement.

Technology stack P0

The shared platform stack (Cosmos DB, Redis, IC-generated API, Angular 21, SQS+SNS, OpenTelemetry, etc.) is documented in the IC Reference. Module-specific additions:

Portal-specific override bindings P1

These overrides are declared in rules/*.rules.json and replace the default for the matching field name pattern.

Versioning — worked example P0

All Patient Portal artifacts are versioned break.feature.bug.buildtimestamp per IC hard rule #9. The example below traces a feature bump on SensitiveClassGating.

SensitiveClassGating 1.0.0.20260515T100000Z — Initial schema. Seven business fields plus three global audit columns (no OrganizationID — deliberate exception). Five sensitive classes: MentalHealth, SUD, HIV, Genetic, Reproductive. Component ic-ng21-portal-1-sensitive-class-gate binds to sensitiveclassgating@1.0.0.* via the DI manifest.

SensitiveClassGating 1.1.0.20260801T120000Z — feature bump — Adds a single optional field, AutoReConsentIntervalDaysInt, to support periodic re-consent prompts (e.g., ask the patient to re-confirm consent every 365 days for SUD data per 42 CFR Part 2 best practice). Per the IC change matrix:

Because the change is backward-compatible, the component tag stays ic-ng21-portal-1-sensitive-class-gate. Existing UI consumers continue to bind sensitiveclassgating@1.x.* and ignore the new field. New UI surfaces that need the re-consent feature bind sensitiveclassgating@^1.1.0. No new database is required (IC rule #13 only applies to break bumps).

SensitiveClassGating 2.0.0.20280101T120000Z — break bump (illustrative) — An illustrative future break bump: SensitiveClassString50 is changed from a free-form String to a strongly-typed Enum with a fixed value set enforced at the DB layer. Per the IC change matrix this is change field type — break bump, EditAMI (90) approval, and per IC rule #13 a new database is provisioned with ETL from the old one. The component tag becomes ic-ng21-portal-2-sensitive-class-gate; consumers must re-bind. The old database stays live for the configured grace period (default 90 days) for rollback.

Patient Portal environment details

Patient Portal RBAC notes

• Patient access. Self-only: the authenticated UserID must match the PatientID in the query. Proxy access is validated through the consent-chain service.
• Sensitive-class gating. Before returning clinical fact data, the API checks SensitiveClassGating for the patient and suppresses categories where IsConsentedBool = false.
• Proxy authorization. Proxy access is validated through the consent-chain service. The proxy’s relationship to the patient, the scope of authorization (full vs. category-limited), and any state minor-consent rules are checked before granting read access.
• VDT compliance. View and Download actions are always available to the authenticated patient (Cures Act information-blocking rule). Transmit actions require the patient to authorize the third-party app through SMART on FHIR consent. Sensitive-class gating is a permitted privacy exception under the information-blocking rule, not a block.

Cross-Module Dependencies

• Scheduling — provides available slots for self-scheduling; receives appointment-confirmed events from the portal.
• Eligibility — provides coverage status and cost estimates at self-scheduling; portal surfaces patient-facing cost information.
• Clinical Documentation — provides encounter notes for AVS generation; clinical facts (allergies, medications, conditions, labs) are global data surfaced via VDT; patient intake flows feed into the clinical intake workflow.
• RCM — provides outstanding statements and balance information for bill-pay; Payment rows reconcile back to RCM.
• Task Management — receives inbound patient messages as task queue items; SLA tracking on message response times.
• eRx / EPCS — medication list surfaced in portal; prescription renewal requests routed through messaging.
• Data Model — sensitive-class gating and read-access audit trail enforce the data ownership contract on every patient data view.
• Terms of Service & Care — consent-chain tracking, proxy authorization, and VDT compliance follow the platform’s authorization model.

Cross-Module Links

• eRx & EPCS — patients view prescription status and formulary results
• RCM — patient statements and payment posting
• Referrals — patients view referral status via portal
• Task Management — SLA breaches create tasks in worklist