Patient & Family Health Portal, Longitudinal Trend Analytics & Digital Clearance

1. Architectural Mission & Consumer Health Principles

In modern clinical diagnostic systems, patient engagement extends far beyond delivering a printed paper voucher at a checkout counter. Patients and caregivers demand transparent, continuous access to their longitudinal health records on mobile devices. They need to monitor chronic metabolic conditions, manage appointments for dependents (such as infant children or aging parents), and securely view verified diagnostic reports without queuing at hospital reception desks.

However, consumer health interfaces introduce significant architectural, security, and clinical challenges:

1. Family Dependency Management: Healthcare decisions rarely occur in isolation. In pediatric and geriatric care, a primary family caregiver manages diagnostic testing for several dependents. Requiring separate user accounts, passwords, and phone verifications for each family member creates high administrative friction and leads to fragmented medical histories.
2. Clinical Prematurity Risks: Exposing unverified raw analyzer telemetry to consumers presents serious clinical hazards. If an unverified automated chemistry analyzer flags a false-positive critical panic value before a pathologist conducts a delta check or microscopic review, the patient may experience severe psychological distress or self-administer inappropriate medications.
3. Revenue Protection & Financial Reconciliation: In outpatient diagnostic centers, providing unconstrained digital access to signed laboratory findings before billing balances are settled leads to uncollected accounts receivable and financial losses.
4. Longitudinal Contextualization: An isolated laboratory report showing a Serum Creatinine of 1.4 mg/dL or Glycated Hemoglobin of 7.2% provides limited value without historical context. Patients require visual trajectories demonstrating whether their clinical biomarkers are improving, stabilizing, or deteriorating under active medical therapy.

Orbit Health resolves these challenges through a unified mobile and desktop patient portal application supported by a deterministic security model. The underlying mechanics are grounded in the production modules under apps/api/src/modules/health/services/portal.service.ts (governing owner-scoped profile management, family retrieval, trend calculations, and report queries), apps/health/src/app/portal/ (the responsive consumer web client), and the relational patients database table.

2. Family Linkage & Dependent Group Code Architecture

To support unified caregiver management without compromising clinical record isolation, Orbit Health implements family group code linkage.

2.1 The Family Code Mechanism (familyCode)

Every patient in the clinical diagnostic network possesses a unique primary medical record number (mrNumber) and an internal UUID in the patients table. When families register together, or when a parent links an infant or elderly dependent, the registration engine assigns a shared group token in patients.familyCode (such as FAM-7712):

2.2 Security Scoping & Cross-Dependent Boundaries

When an authenticated user requests family data via family(patientId, tenantId), the portal service executes a two-stage authorization verification:

1. Owner-Scoped Verification: The service confirms that patientId matches the authenticated session token subject. If a user attempts to supply another patient identifier, the query yields a 404 Not Found response.
2. Family Member Query: If the patient record contains a non-null familyCode, the query retrieves all dependent profiles sharing that code, explicitly excluding the primary user identifier:
   • where: { tenantId, familyCode: me.familyCode, id: { not: patientId } }
3. Consolidated Report Aggregation: The service queries up to 50 finalized reports associated with the retrieved family member identifiers. This allows a mother to view her child pediatric immunology panel directly from her family dashboard without switching login sessions.

3. Strict Clinical Release Boundaries & Report States

To protect patient safety and preserve clinical ethics, the diagnostic portal enforces strict state machine gates before exposing results to consumer views.

3.1 The Visibility Query Invariant

In apps/api/src/modules/health/services/portal.service.ts, methods myReports and myReport strictly enforce the following persistence criteria:

where: {
  tenantId: activeTenantId,
  patientId,
  status: { in: ['COMPLETED', 'APPROVED'] }
}

Any report whose status is collected, received, in progress, or preliminary evaluates to null or empty array in consumer viewports. Even if an accession barcode exists and sample tubes are actively running on an automated chemistry track, the patient sees only a neutral processing status indicator: Laboratory Analytical Evaluation in Progress.

Once the consulting pathologist executes digital signoff as detailed in Diagnostic Report Lifecycle & Autoverify Rules, the report transitions to completed status and instantly appears in the patient portal.

4. Longitudinal Biomarker Analytics & Trend Graphs

The cornerstone of chronic illness management within Orbit Health is the longitudinal trend analysis engine.

4.1 Analyte Data Extraction Algorithm

When a user requests analytical trends via trends(patientId, series, tenantId), the backend application server executes an aggregation routine:

1. Querying Finalized Results: The system retrieves all lab_report_results records linked to reports where patientId matches the authenticated user and status equals completed.
2. Series Grouping: Results are grouped by analyte component name (such as Glycated Hemoglobin, Serum Creatinine, Fasting Blood Sugar, Total Cholesterol).
3. Point Vector Extraction: For each component, the engine constructs a time-sorted vector of measurement points:
   • date: Extracted from the diagnostic report completion timestamp (formatted as YYYY-MM-DD).
   • value: The quantitative numeric measurement result.
   • min: The snapshotted biological lower reference threshold (rangeMin).
   • max: The snapshotted biological upper reference threshold (rangeMax).
4. Normal Range Band Visualization: The dynamic client view engine renders an interactive time-series curve plotted against an illuminated horizontal reference band representing the physiological normal interval.

4.2 Interactive Analyte Trend Schematic

The following responsive visualization demonstrates a four-point longitudinal trend for Glycated Hemoglobin (HbA1c) spanning a 12-month clinical management window:

5. Software User Interface Specification

The following smartphone interface illustrates the mobile consumer application experience for an authenticated family primary account holder:

6. Digital Pre-Payment Clearance Gates & Invoicing Integration

Diagnostic laboratories frequently perform complex inpatient or outpatient testing where billing balances remain pending prior to final report generation. To prevent uncollected accounts receivable, Orbit Health integrates a digital pre-payment clearance gate.

6.1 Clearance Evaluation Sequence

In apps/api/src/modules/health/services/portal.service.ts, the method myInvoices retrieves patient billing records with line-item breakdowns, invoice payment statuses (Paid, Partial, Unpaid), and live receipt histories. When a patient clicks the Download Signed Official Report (PDF) button in the portal interface, the system executes the following verification:

1. Invoice Balance Calculation:
   • The modular backend application server identifies all invoices linked to the patient accession in the database persistence kernel via myInvoices.
   • It computes the live outstanding debt:
     • outstanding = sum(invoice.totalAmount - invoice.paidAmount)
2. Clearance Decision:
   • Case A: Zero Outstanding Balance (outstanding == 0.00): The digital clearance gate opens immediately. The application server issues an authorized signed URL allowing the client browser to stream the watermarked PDF report stamped with a cryptographic SHA-256 digest.
   • Case B: Outstanding Balance (outstanding > 0.00): The digital clearance gate halts execution with an HTTP 403 Forbidden exception: Report is held pending payment of outstanding dues.
3. Consumer Settlement Flow:
   • The user interface intercepts the 403 response and renders an in-app payment modal displaying the unpaid balance (such as $45.00).
   • The patient selects a digital settlement channel (such as an integrated credit card rail or regional mobile wallet).
   • Upon payment clearance, the billing service registers a payment entry against the invoice, updating its status to paid.
   • The clearance gate re-evaluates to zero outstanding dues, instantly triggering the report download.

For public-facing QR verification of printed physical reports where identical financial clearance gates apply, review Tamper-Proof QR Code Verification & Financial Clearance Gates.

7. Online Appointment Scheduling & Intake Workflow

The patient portal provides integrated self-scheduling for phlebotomy venipunctures, diagnostic ultrasounds, and specialist physician consultations, orchestrated by the myAppointments service handler.

7.1 Real-Time Capacity & Conflict Detection

The scheduling engine (apps/api/src/modules/health/services/scheduling.service.ts and portal.service.ts method myAppointments) manages facility capacity through deterministic operational constraints:

• Time-Slot Allocation: Each phlebotomy station accommodates appointments in fifteen-minute increments (such as 08:00 to 08:15, 08:15 to 08:30). Patients select available calendar slots and press Enter to confirm booking reservation (or tap Esc to dismiss slot details).
• Fasting Window Optimization: The scheduling interface highlights morning fasting slots (07:00 to 10:00 AM) for metabolic panels, warning patients of mandatory 8-to-12 hour fasting prerequisites.
• Home Blood Collection Dispatch: When a patient requests home phlebotomy for an elderly family member, the system verifies geographic service zones and reserves an authorized field phlebotomist route, assigning transport cooler equipment.

8. Failure Modes & Operational Recovery SOP

The following operational matrix details consumer portal failure modes, root causes, and technical recovery workflows:

9. Security, Privacy & Compliance Verification

To maintain rigorous compliance with HIPAA, GDPR, and ISO 27001 healthcare data standards, the patient portal implements comprehensive digital security safeguards:

1. Strict Session Token Expiration: Consumer session tokens enforce a tight sixty-minute active lifespan with rolling refresh tokens invalidating upon browser session termination.
2. Immutable Access Auditing: Every query to myReport, trends, or family emits a structured audit log entry recording the accessing IP address, device user-agent string, patient identifier, and accessed accession reference.
3. Cryptographic At-Rest Document Encryption: Diagnostic report PDFs stored in object storage are encrypted using AES-256 with unique tenant-level keys. Pre-signed retrieval links enforce strict sixty-second expiration limits, preventing unauthorized link sharing.

For details on referring physician access to patient records, review Referring Doctor Portal, Clinical Volumes & Commission Settlement Accounting. For laboratory quality control protocols and Westgard analytical evaluation, refer to Levey-Jennings QC & Westgard Multirule Evaluation.