VitalTrace

01. Problem & Clinical Motivation

Diagnostic laboratory reports represent one of the most critical, yet fragmented, categories of personal health data. Patients accumulate scattered physical PDFs, paper printouts, and photographic scans across different healthcare providers and lab chains.

When engineers attempt to ingest these documents with modern multimodal Large Language Models, two dangerous failure modes emerge:

02. End-to-End System Architecture

VitalTrace couples a React 19 frontend with server-side Supabase Edge Functions, enforcing strict separation between data extraction, deterministic clinical validation, and patient review.

[ Lab Report PDF / Scan ]
        │
        ▼
[ Private Supabase Storage Vault ] ───► Encrypted at rest (AES-256)
        │
        ▼
[ Edge Function: extract-report ] ────► Gemini 1.5/2.5 Multimodal Extraction
        │
        ▼
[ Strict Zod Schema Parsing ] ────────► ExtractedReportSchema Validation
        │
        ▼
[ Deterministic Validator Engine ]
  ├── Biological Plausibility Check ──► PLAUSIBILITY_BOUNDS screening
  ├── LOINC Alias Dictionary ─────────► Canonical mapping (null fallback)
  ├── Unit Harmonization ─────────────► mg/dL, mmol/L, x10^3/uL
  └── Duplicate Collision Audit ──────► Same analyte + date in batch
        │
        ▼
[ PostgreSQL Database (3NF) ] ────────► status = 'pending' (RLS Auth Enforced)
        │
        ▼
[ Human Review Workbench ] ───────────► Clinician / Patient Verification Gate
        │
        ▼
[ Longitudinal Trajectories ] ────────► PostgreSQL security_invoker Views

03. Deterministic Validator Engine

Implemented in src/lib/validationRules.ts, the validator operates after Zod parsing and enforces four non-negotiable checks:

• 01
  Physiological Plausibility Limits:

  Evaluates readings against hard human physiological bounds. For example, Potassium must fall between 1.0 and 10.0 mmol/L; values exceeding these trigger a CRITICAL_PLAUSIBILITY_BREACH.

• 02
  Zero-Hallucination LOINC Dictionary:

  Maps synonyms (e.g. “Fasting Blood Sugar”, “Glucose Plasma”) to canonical code 1558-6. Any unmapped test retains its raw string name with a null LOINC code.

• 03
  Unit Harmonization & Audit:

  Flags missing units or incompatible unit representations before numeric trends are plotted.

• 04
  Duplicate Collision Detection:

  Identifies conflicting readings for the same biomarker within the same specimen draw date.

04. Multi-Tenant Isolation & SQL Security

In healthcare applications, tenant data leakage is intolerable. VitalTrace enforces complete Row-Level Security (RLS) across all tables:

CREATE OR REPLACE VIEW view_patient_biomarker_trajectories
WITH (security_invoker = true) AS
SELECT 
  obs.profile_id,
  obs.loinc_code,
  obs.canonical_name,
  obs.observation_date,
  obs.value_numeric,
  obs.unit
FROM observations obs
WHERE obs.status = 'confirmed';

By specifying WITH (security_invoker = true), PostgreSQL enforces the querying user's credentials rather than the view owner's permissions, eliminating auth bypass vulnerabilities across analytical queries.

05. Automated Testing & Verification

The repository includes a comprehensive automated test suite executed via Vitest. The suite covers biological boundary checks, dictionary aliases, Zod schema invariants, and the idempotent retry engine:

06. Current Limitations & Roadmap

• !Clinical Scope: VitalTrace is an engineering demonstration of data quality architectures and is not a certified diagnostic medical device.
• ▸Roadmap 1: Direct HL7 FHIR Observation resource export for interoperability with hospital EHR systems.
• ▸Roadmap 2: Expanded LOINC dictionary coverage to pathology narratives and microbiology culture reports.