Patient Portal

Patient-facing dashboard for prescriptions, shipments, messaging, and telehealth.

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
• Practitioner Routing — Messages are sent to the patient's assigned practitioner
• Read Receipts — Messages are marked as read when viewed
• Thread View — Conversation-style chronological message display

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