Patient Portal

White-labeled patient-facing app. Hostname-based org resolution, Clerk auth with org-scoped sessions, live canvas-client reads. Stateless — no DB.

Overview

The Patient Portal is an Express 5 BFF (Backend for Frontend) serving a React SPA at patient.hisera.com. It runs on ECS behind the ALB at priority 5 and provides patients with a self-service dashboard for managing their prescriptions, tracking shipments, messaging their care team, and scheduling telehealth appointments.

The BFF layer handles authentication, session management, and proxies requests to both Canvas FHIR and the Integration Service, ensuring patients only see their own data.

Architecture

┌──────────────────────────────────────────┐
│  patient.hisera.com (ECS via ALB)        │
│  Express 5 BFF + Vite React SPA          │
└───────────┬──────────────┬───────────────┘
            │              │
   Canvas FHIR API    Integration Service
   │                  │
   ├─ Patients        ├─ Shipments
   ├─ MedicationReq   ├─ Notifications
   ├─ Communications  ├─ FedEx Tracking
   └─ Appointments    └─ Scheduling

Infrastructure

Authentication

The Patient Portal supports two authentication methods. Both result in a JWT session cookie with a 4-hour expiry.

Email OTP

Patients enter their email address and receive a verification code via SendGrid. The code is validated server-side and a JWT session cookie is set.

Canvas OAuth SSO

Patients who access the portal from a Canvas magic link are authenticated via Canvas OAuth. The BFF exchanges the authorization code for a Canvas access token, looks up the patient, and issues a JWT session cookie.

Dashboard

The dashboard is the patient's landing page after authentication. It displays a personalized greeting and a summary of their active treatment.

Dashboard Components

• Greeting - Personalized with the patient's first name from Canvas FHIR
• Active Subscriptions - Current medication, dosage, and next refill date
• Shipment Tracker - Most recent shipment status with tracking link
• Telehealth Status - Upcoming appointment or option to schedule
• Notifications - Unread notification count badge

Prescriptions

The Prescriptions page displays the patient's medication history from Canvas FHIR MedicationRequest resources. Each prescription shows the medication name, dosage, prescriber, status, and date written.

Prescription Fields

Shipments

The Shipments page shows all shipments for the patient, sourced from the Integration Service database. Each shipment includes real-time FedEx tracking data with a Leaflet map visualization.

Tracking Map

When a shipment has an active tracking number, the portal displays a Leaflet map (using CARTO Voyager tiles) with a pulsing location dot showing the package's last known location. The map is code-split into a ~47KB chunk and only loaded when needed.

Shipment Status Flow

label_created → packed → shipped → delivered
                                     ↘
                                  voided

Messages

The Messages page provides a secure messaging interface between the patient and their assigned care team. Messages are stored as Canvas FHIR Communication resources and auto-polled every 15 seconds for new messages.

Features

• Auto-Polling - New messages checked every 15 seconds via setInterval. The polling interval ensures near-real-time message updates without WebSocket complexity.
• Practitioner Routing - Messages are routed to the patient's generalPractitioner from their Canvas FHIR Patient resource. If no general practitioner is assigned, the system falls back to the default practitioner configured in the integration service.
• Read Receipts - Messages are marked as read when viewed
• Thread View - Conversation-style chronological message display

Refill Management

The Subscriptions page allows patients to view and manage their recurring prescription refills. Each refill schedule shows the medication, next refill date, refills sent out of the total allowed, and current status. Patients have full self-service control over their refill schedules.

Patient Actions

• Pause - Temporarily suspend refills. Opens a modal where the patient can set an optional resume date. The schedule moves to paused status.
• Resume - Reactivate a paused schedule via an inline button. The next refill date is recalculated from today.
• Delay - Push the next refill to a custom future date without pausing the schedule.
• Cancel - Permanently cancel remaining refills. Opens a confirmation modal. This action cannot be undone.

UI Components

• SubscriptionsPage - Main page listing all refill schedules with status badges and action buttons
• Pause Modal - Date picker for optional resume date
• Cancel Modal - Confirmation dialog with reason selection
• Status Display - Shows next refill date, refills sent/total count, and color-coded status badge

API Endpoints

Scheduling

The Scheduling page allows patients to book, reschedule, and cancel telehealth appointments. The availability engine checks practitioner schedules and the Zoom integration creates meeting links automatically.

Booking Flow

1. Patient selects a date from the availability calendar
2. Available time slots are displayed based on practitioner schedules
3. Patient selects a time slot and confirms the appointment
4. A Zoom meeting is created automatically via the Zoom API
5. Confirmation is sent to the patient via email and in-app notification

Notifications

The notification system provides persistent, database-backed notifications delivered via the Integration Service. Notifications are displayed as an in-app feed with an unread count badge on the dashboard.

Notification Types

• Shipment Shipped - Triggered when shipment status transitions to "shipped"
• Shipment Delivered - Triggered when FedEx confirms delivery
• Prescription Approved - Triggered after orchestrator approval pipeline
• Appointment Reminder - Sent 24 hours before a telehealth appointment
• New Message - Triggered when the care team sends a message
• Refill Upcoming - Sent 7 days before a scheduled refill

API Endpoints

All /api/patient/* endpoints require a valid JWT session cookie. The BFF enforces patient-scoped access - patients can only view their own data.

Authentication

Patient Data