Building a Healthcare Patient Portal: Architecture, Security, and Compliance

What a Patient Portal Actually Needs

A patient portal is not just a website with a login screen. It is a regulated system that handles Protected Health Information (PHI), requires audit logging of every data access, must support secure messaging between patients and providers, and needs to integrate with clinical systems. Done correctly, it dramatically reduces administrative burden and improves patient outcomes. Done incorrectly, it creates compliance liability.

Core Architecture

The stack I use for healthcare portals: Next.js for the frontend, NestJS for the API, PostgreSQL for structured data, and S3 with server-side encryption for documents. All services communicate over TLS. The API runs behind a WAF (Web Application Firewall) that blocks common attack patterns before they reach application code. Infrastructure lives in a HIPAA-eligible environment — AWS or Azure both offer this with a signed BAA.

Authentication and Session Management

Healthcare applications require stronger authentication than typical SaaS. Implement multi-factor authentication as mandatory, not optional. Use short session timeouts (15-30 minutes of inactivity) with explicit re-authentication for sensitive actions like viewing clinical notes or sending messages. Log every authentication event — successful logins, failed attempts, password resets — with timestamp and IP address.

Secure Messaging

Patient-provider messaging must be encrypted at rest and in transit. Store messages in an encrypted database column, not in plain text. Notify providers of new messages via email without including any PHI in the notification — just a link back to the portal. Implement message threading and read receipts. Retain messages for the period required by your jurisdiction's regulations.

Document Management

Patients upload insurance cards, intake forms, and ID documents. Providers upload lab results, imaging, and treatment plans. Store all documents in S3 with server-side encryption using KMS. Generate pre-signed URLs with short expiry (15 minutes) for document access — never expose raw S3 URLs. Run a malware scan on every uploaded file before making it accessible.

Appointment Scheduling

The scheduling system must handle provider availability, appointment types with different durations, recurring appointments, cancellation policies, and automated reminders. Integrate with the provider's existing calendar (Google Calendar or Microsoft 365) to prevent double-booking. Send reminders at 72 hours, 24 hours, and 2 hours before the appointment via the patient's preferred channel.

The Audit Log

Every read, write, and delete operation on PHI must be logged immutably. Store audit logs in a separate database with write-only access from the application. Include: user ID, patient ID, action type, resource accessed, timestamp, and IP address. Retain for six years minimum. Make logs searchable for compliance investigations.

PSI Nest, one of my case study projects, is a full HIPAA-compliant practice management system built with this architecture. Read the case study or reach out to discuss your healthcare project.