# GENOMA — Patient, Physician & Administrator System Capabilities Specification

> **Purpose of This Document:** This specification defines **what** the GENOMA system offers to **Patients** (and their delegated Caregivers / Sponsors), **Treating Physicians**, and **Platform & Clinical Operations Administrators**—covering all implemented and planned domain capabilities, clinical/operational data, medical and governance rules, regional realities, and security boundaries.
>
> **Intentional Omission of Presentation Details:** This document contains **zero** prescriptions regarding visual design, information architecture, grouping, ordering, navigation mechanics, interaction patterns, or display structures. Any designer or agent consuming this specification has complete creative autonomy over how capabilities are organized, prioritized, revealed, and experienced.

---

## 1. Platform Mission, Regional Context & Core Clinical Model

### 1.1 The Problem Addressed (Venezuela & Latin America)
1. **Fragmented Clinical History:** Patients routinely carry physical folders (*carpetas de exámenes*) between laboratories, imaging centers, and private offices. Blood tests, vital sign trends, imaging reports, and prescriptions remain scattered across paper printouts or isolated files.
2. **Late-Stage Reactive Care:** Medical attention often begins only after chronic conditions (Type 2 diabetes, severe hypertension, chronic kidney disease, advanced cardiovascular or hepatic disease, hereditary malignancies) have already caused irreversible damage.
3. **Disconnected Consumer Genomics:** Direct-to-consumer DNA reports lack clinical quality sign-off, ignore the patient's real laboratory values and active prescriptions, omit local commercial medication names, and have no connection to the patient's treating physicians.

### 1.2 Core Clinical Thesis: Verified Genotype × Living Phenotype × Active Treatment
GENOMA unites **clinically verified genomic data** with **longitudinal clinical records** so individuals can act preventively every day and physicians can intercept disease risk early:
- **Immediate Utility Before DNA Sequencing:** Every longitudinal clinical capability (vitals, laboratory observations, multi-specialty diagnostic studies, symptom/diagnosis history, medication tracking, consultations, and referrals) works from day one—even before a patient has taken a genetic test. When clinical observations suggest hereditary susceptibility, the system identifies targeted genetic panels that would refine care.
- **Strict Clinical Quality Gate:** Raw sequencing files (`VCF`/`BCF`) uploaded by diagnostic laboratories never generate patient insights or physician decision rules until a licensed specialist (`ClinicalVerifier`) validates reference assembly provenance (`GRCh38`/`GRCh37`), sequencing quality thresholds (`mean DP >= 30`, `mean GQ >= 20`, `PASS >= 95%`), and two-person separation (`uploaded_by != verified_by`), sealing approval with a cryptographic `SHA-256` digest.
- **Continuous Cross-Evaluation:** Whenever new laboratory values, vital signs, symptoms, prescriptions, or `ClinVar`/`CPIC` scientific reclassifications arrive, the Clinical Decision Support System (`CDSS`) re-evaluates the interplay between genetics, physiology, and pharmacology.
- **Regional & Bilingual Reality:** Built primary-first for Venezuelan and Latin American clinical practice (`es-LA` terminology, *Perfil 20 Venezolano* laboratory conventions, local commercial pharmacy brands alongside generic active ingredients, local installment financing, and cross-border diaspora family sponsorship), with full English (`en`) support for international travel, foreign hospitals, and diaspora relatives.

### 1.3 Identity, Cryptographic Custody & Conflict-of-Interest Invariants
- **Zero-Trust Authentication & Civil/Clinical Credentials:** OAuth 2.1 (`PKCE S256`) and biometric/hardware Passkeys (`WebAuthn` `ES256`/`EdDSA`) with short-lived (`900-second`) authenticated sessions and instant revocation. Records support Venezuelan civil identity (*Cédula de Identidad* `national_id_cedula`, `E.164` phone, municipality/address), physician *MPPS* medical license verification (`medical_license_mpps`), and healthcare organization tax registration (*RIF* `tax_id_rif`).
- **Patient-Bound Envelope Encryption:** Diagnostic studies, `DICOM` imaging, and genomic callsets are sealed under compartment-isolated `AES-256-GCM` envelope encryption cryptographically bound (`AAD`) to the specific `patient_id`, preventing cross-patient file substitution.
- **Multi-Role Separation of Duties:** A single person may hold multiple roles (for example, a licensed physician who is also registered as a patient or administrator), governed by strict invariants:
  - **`SelfTreatmentProhibited`:** A physician cannot record official clinical consultations, diagnoses, or prescriptions for their own personal patient record (`doctor_id == patient_id`).
  - **`SelfReferralConflict`:** A physician cannot issue a specialist referral naming themselves as the receiving specialist.
  - **`SelfVerificationProhibited`:** No genomic dataset or variant reclassification can be verified by the same user who uploaded it.
  - **`SelfDiagnosticUploadProhibited`:** A laboratory technician cannot upload or certify official diagnostic test results for their own patient record.
  - **Sovereign Patient Custody:** No physician or organization can access a patient's longitudinal record or diagnostic compartments without active consent granted by that patient (or their authorized legal caregiver).

---

## 2. Patient Capabilities (Final User, Family Caregiver Proxy & Diaspora Sponsor)

### 2.1 Acting Contexts & Delegated Care
- **Sovereign Personal Holder:** Full access to inspect and manage one's own longitudinal health data, genomic traits, diagnostic files, medication safety checks, appointments, consent grants, payments, and portable exports.
- **Authorized Family Caregiver Proxy:** Managing care on behalf of dependent relatives (such as children or elderly parents) within explicitly authorized medical compartments, keeping each person's longitudinal state strictly separate so one family member's data is never confused with another's.
- **Cross-Border Diaspora Sponsor:** Relatives living abroad (e.g., United States, Spain, Colombia, Chile, validated via ISO-3166 country code) sponsoring preventive plans across three tiers—`Essential EHR ($15 USD/mo)`, `Preventive Care Plus ($25 USD/mo)`, or `Complete Genomic Family ($35 USD/mo)`—as well as genetic panels or consultations for beneficiaries in Venezuela, with full lifecycle control (`Active`, `Paused`, `Cancelled`). Unless separately granted clinical caregiver proxy consent, a sponsor only sees sponsorship status/settlements, sample-collection logistics, and preventive triage notifications when `shareTriageAlertsWithSponsor` is enabled by the beneficiary—never private consultation notes or raw clinical records.

### 2.2 Baseline Health Profile, Vital Signs & Genomic Readiness
- Personal demographics, Venezuelan *Cédula* (`national_id_cedula`), biological sex (`Male`, `Female`, `Intersex`), date of birth, contact/municipality details, designated primary physician and primary clinic, blood type, emergency contacts, documented drug/food allergies and intolerances, and multi-generation family medical history.
- Longitudinal anthropometrics and vital signs: height (`cm`), weight (`kg`), waist circumference (`cm`), calculated `BMI` (`Underweight`, `Normal`, `Overweight`, `Obesity Class I / II / III`), and systolic/diastolic blood pressure (`Normal`, `Elevated`, `Hypertension Stage 1 / Stage 2`, `Hypertensive Crisis`).
- Genomic profile verification state: visibility into whether a DNA sample is in transit/processing, awaiting specialist quality verification (`PendingVerification`), rejected for laboratory re-run (`Rejected`), or `ClinicallyVerified` (including whether retroactive `ClinVar`/`CPIC` variant reclassifications have updated prior findings).

### 2.3 Six Physiological System Assessments & Priority Biomarker Rechecks
- Synthesized health evaluation (`0–100` quantitative score, status tier `Optimal` / `Attention Needed` / `Action Required`, 6-month historical trajectory delta, contributing biomarkers and genes, and plain-language explanation) across six physiological systems:
  1. **Cardiovascular** (Heart & Blood Vessels)
  2. **Metabolic & Endocrine** (Glucose Regulation, Lipids, Weight & Hormones)
  3. **Renal** (Kidneys, Filtration & Electrolytes)
  4. **Hepatic & Gastrointestinal** (Liver, Digestion & Mucosal Health)
  5. **Immune & Inflammatory**
  6. **Neurological & Cognitive Longevity**
- **Person-Centric Priority Biomarker Rechecks:** Individualized retest schedules and countdowns (`recommendedRecheckDays`) triggered by the person's specific genetic variants, age/sex thresholds, or active medications (for example, periodic `uACR` urine screening for `APOL1` kidney-risk carriers or `HbA1c` tracking for `TCF7L2` carriers), plus the ability to request follow-up care when any physiological system requires attention.

### 2.4 Actionable Daily Prevention, Modifiable Risk & Wellness Genomics
- **Stop / Start Preventive Action Plan:** Personalized, plain-language daily habits divided into behaviors/exposures/foods to **stop or avoid** and nutrition/movement/hydration/screening habits to **start**, grounded simultaneously in verified genetics and current laboratory biomarkers, with progress tracking and the ability to flag items to discuss with the treating physician.
- **Modifiable 10-Year Disease Risk Attenuation:** Polygenic Risk Score (`PRS`) percentiles calibrated to biogeographical ancestry, demonstrating how improving modifiable clinical factors (such as `BMI`, blood pressure, `LDL-C`, or fasting glucose) lowers 10-year disease probability despite inherited genetic predisposition.
- **Nutrigenomics, Athletic Recovery & Chronobiology:** Correlation of inherited metabolic/nutrient variants (`MTHFR` folate `B9`, `VDR` vitamin `D`, `HFE` iron, `FUT2` vitamin `B12`, `MCM6` lactose tolerance, `APOA2` saturated fat response, `FADS1` omega-3 conversion) directly alongside actual measured blood levels, plus `CYP1A2` caffeine metabolism speed, `ACTN3` muscle fiber profile, `COL1A1` soft-tissue/tendon recovery, and `CLOCK` circadian sleep-wake tendencies.
- **Targeted DNA Panel Discovery:** Contextual identification of specific targeted panels (`Metabolic & Hepatic Panel`, `Cardio-Renal Panel`, `Pharmacogenomics Safety Panel`, `Celiac, GI & Nutrition Panel`) with target genes, clinical rationale, expected benefit, and USD pricing based on existing out-of-range blood tests or family history for users who do not yet have full genomic data.

### 2.5 Biogeographical Ancestry, Founder Risks, Recessive Carrier Status & Couple Compatibility
- **Clinically Actionable Admixture & Lineages:** Ancestral population proportions (Southern European/Iberian, Indigenous Amerindian, Sub-Saharan West African, Sephardic/Mediterranean, East/South Asian), maternal (`mtDNA`) and paternal (`Y-DNA`) haplogroups, archaic `Neanderthal` and `Denisovan` introgression percentages, and **ancestry-informed clinical founder alerts** (explaining population-enriched risks such as West African `APOL1`/`HBB`/`ACKR1`, Amerindian `PNPLA3`/`SLC16A11`, or Mediterranean/Sephardic `G6PD`/`BRCA`).
- **Personal Recessive Carrier Screening:** Identification of healthy heterozygous carrier status for autosomal recessive conditions (`CFTR` cystic fibrosis, `SMN1` spinal muscular atrophy, `HBB` sickle cell / beta-thalassemia, `GJB2` hearing loss, `PAH`, etc.).
- **Dual-Consent Couple Carrier Compatibility:** Mendelian reproductive compatibility check between two consenting adult profiles (`partnerA != partnerB`), computing offspring carrier (`50%`) and affected (`25%`) probabilities when both partners carry variants in the same recessive gene, paired with access to specialist genetic counseling (`SVGH`).

### 2.6 Pre-Intake Medication Safety & Cryptographic Emergency Record
- **Medication & Commercial Brand Compatibility Check:** Evaluating any candidate drug—by generic active ingredient or local Venezuelan pharmacy brand (*Lipitor*, *Plavix*, *Cataflam*, *Tegretol*, *Zyloprim*, *Amikacina*, etc.)—against verified pharmacogenomic genes (`CYP2C19`, `CYP2D6`, `SLCO1B1`, `CYP2C9`, `VKORC1`, `DPYD`, `RYR1`, `CACNA1S`, `G6PD`, `HLA-B*15:02`, `HLA-B*57:01`, `HLA-B*58:01`, `MT-RNR1`), documented allergies, active prescriptions (polypharmacy interactions), and clinical risk factors (such as NSAID nephrotoxicity in `APOL1` carriers or hemorrhage risk during dengue fever). Returns `Safe (Standard Dose)`, `Caution (Dose Adjustment Needed)`, or `Contraindicated (Avoid)`, plain-language rationale, and safer therapeutic options to review with a physician.
- **Cryptographically Signed Emergency Pharmacogenomic & Surgical Record:** Portable, verifiable (`Ed25519` digital signature + scannable `QR` URI + offline/printable export) emergency summary exposing severe allergies, blood type, high-risk drug contraindications, malignant hyperthermia/anesthesia warnings (`RYR1`/`CACNA1S`), and aminoglycoside ototoxicity alerts (`MT-RNR1`) for paramedics, emergency physicians, surgeons, and pharmacists, available in Spanish and English.

### 2.7 Multi-Specialty Diagnostic Repository & Longitudinal Biomarkers
- Unified custody, `SHA-256` integrity verification, specialist attribution, plain-language clinical findings summaries, and download/sharing across **6 diagnostic categories**:
  1. **Genomics & Molecular Reports**
  2. **Clinical Bioanalysis & Laboratory Blood/Urine Panels**
  3. **Sonography, Ecography & Doppler Studies**
  4. **Radiology Imaging** (`X-Ray`, `CT`, `MRI`, Mammography, Bone Densitometry — including `DICOM` study access and plain-language radiology summaries)
  5. **Cardiopulmonary Diagnostics** (`12-Lead ECG`, Holter, Echocardiogram, Spirometry)
  6. **Histopathology & Biopsy Reports**
- Multi-visit `LOINC` biomarker histories evaluated against biological-sex and age-stratified `CALIPER`/`IFCC` physiological intervals (`Critical Low`, `Low`, `Normal`, `Optimal`, `High`, `Critical High`), supporting both conventional (`mg/dL`, `ng/mL`, `U/L`) and international `SI` (`mmol/L`, `µmol/L`, `µkat/L`) units, including automated `HL7 FHIR R4` ingestion from partner laboratories.

### 2.8 Appointments, `<48h` Study Interpretation, Home Phlebotomy & Telehealth
- Lifecycle management of medical appointments across both physician-proposed preventive visits (`PreventiveMetabolic`, `OncologySurveillance`, `PgxMedicationReview`, `CardioRenalProtection`, `GeneticCounseling`, `GeneralFollowUp` across `Proposed` -> `Confirmed` -> `Completed` | `Cancelled`) and patient-initiated requests (`RequestedDirectDoctor` | `RequestedClinicQueue` -> `AssignedByClinic` -> `Confirmed` -> `InConsultation` -> `CompletedWithNotes` | `Cancelled`), automated `24h` reminders, pre-visit laboratory requisitions ordered by physicians, and post-visit consultation summaries/diagnoses/treatment plans.
- **Four Care & Diagnostic Request Modes:**
  1. **Direct Physician Scheduling:** Selecting an open availability slot with a chosen specialist (in-person or remote).
  2. **Multi-Specialty Clinic Routing:** Requesting care by medical specialty at a partner clinic for assignment to the next available physician.
  3. **`<48h` Rapid Exam Interpretation (*Lectura de Exámenes*):** Submitting recently uploaded bloodwork or imaging studies for rapid physician review within 48 hours.
  4. **Home Sample Collection (*Toma de Muestra a Domicilio*):** Scheduling at-home phlebotomy blood draws or DNA swab collection with municipality/address details, pre-collection fasting requirements (`8–12h`), courier tracking, specimen chain-of-custody stages (`Scheduled` -> `En Route` -> `Cold-Chain Verified 2.0–8.0 °C` -> `Received at Lab`), and real-time temperature provenance.
- **Encrypted Remote Consultations (`WebRTC` Telehealth):** Participating in confirmed video/audio consultations protected by ephemeral `900-second` `HMAC-SHA256` participant tokens, live clinical media review with the doctor, and post-call care instructions.

### 2.9 Sovereign Privacy, Multi-Channel Alerts, Financing & International Portability
- **Granular Compartment Consent & Revocation:** Inspecting every physician and healthcare organization holding access; approving or denying specialist referral access requests with per-compartment granularity (`Vitals`, `Bioanalysis`, `Ecography`, `Radiology`, `Cardiology`, `Genomics`, `Biopsy`); revoking any active permission with immediate effect; and inspecting immutable audit records of who accessed the record and why.
- **Zero-PHI Notification Channels:** Managing delivery preferences and delivery receipts across `WhatsApp Business`, `Transactional Email`, and `WebPush` (enforcing strict `Zero-PHI` redaction so raw genotypes, `rs` IDs, gene symbols, or `LOINC`/`HPO` codes never traverse external messaging relays).
- **Multi-Rail Checkout & Installment Financing:** Paying for panels, consultations, or family sponsorships across settlement states (`PendingCheckout` -> `Authorized` -> `Settled` | `Failed` | `Refunded`) via:
  - **Cashea `0%` APR Split-Installments** (minimum `$20.00 USD`, selectable `40%`, `50%`, or `60%` initial payment + 3 biweekly installments at `+14d`, `+28d`, and `+42d` with exact-cent conservation),
  - **`Stripe USD`** international payment method,
  - **`Crypto USDT`** settlement, or
  - **`Partner Clinic Invoice USD`**, with complete settlement receipts.
- **Smart Health Passport Export:** Generating a cryptographically verifiable (`integritySha256` + OpenBao Transit `Ed25519` signature, `signingKeyId`, and `signerPublicKeyHex`) `HL7 FHIR R4` JSON bundle or bilingual clinical PDF summary tailored to a destination country or external hospital.
- **Patient Boundaries:** Patients never view other patients' records, never bypass clinical quality verification on raw sequencing files, and never author official `ICD-10` diagnoses or medical prescriptions.

---

## 3. Physician Capabilities (Treating Doctor, Clinic Specialist & Referred Consultant)

### 3.1 Practice Contexts & Daily Clinical Operations
- **Multi-Patient Practice Reality:** A physician manages an entire clinical practice of consented patients—tracking scheduled consultations, urgent clinical escalations across patients, follow-up adherence, and incoming specialty requests—and drills into an individual patient's longitudinal record when conducting an encounter, triaging an alert, or reviewing a roster member (never locked to a single hardcoded patient).
- **Three Physician Operating Contexts:**
  1. **Solo Medical Practice (`SoloPracticeFirm`):** Personal patient roster, direct consultation schedule, custom availability slot publishing (dates, durations `30m`/`45m`/`60m`, fees, in-person/telehealth modalities), and outbound referrals to external specialists.
  2. **Multi-Specialty Clinic (`MultiSpecialtyClinic`):** Claiming unassigned specialty appointment requests and `<48h` rapid study interpretation requests routed to the clinic, coordinating inter-specialty handoffs, and reviewing clinic preventive retention metrics (active patient base, preventive consultations generated, repeat diagnostic orders).
  3. **Referred Specialist:** Accessing only the specific medical compartments (`Vitals`, `Bioanalysis`, `Ecography`, `Radiology`, `Cardiology`, `Genomics`, `Biopsy`) granted by the patient for that referral, with the ability to request additional compartments with clinical justification when needed.
- **Workload, Readiness & Outreach:** Tracking consultations completed today, this week, and this month across visit types (new patient, preventive follow-up, `<48h` exam reading, urgent alert intervention); checking consultation check-in state (`Waiting`, `In Consultation`, `Completed`, `No-Show`); verifying whether pre-visit `LOINC` laboratory panels ordered for today's patients have already arrived from partner labs; identifying patients overdue for follow-up or labs; and dispatching privacy-safe (`Zero-PHI`) `WhatsApp Business`, `Email`, or `WebPush` reminders.

### 3.2 Proactive Clinical Triage & `<4-Hour` SLA Escalations
- Automated priority-ranked clinical alerts (`Urgent / Critical`, `Priority`, `Routine`) across the physician's consented patient population whenever:
  - Newly ingested laboratory biomarkers or vital signs collide with verified high-risk genotypes (e.g., `APOL1` G1/G2 + Stage 2 hypertension or elevated `uACR`; `LDLR`/`APOB`/`PCSK9` + severe `LDL-C`/`ApoB` elevation; `TCF7L2` + `PNPLA3` + elevated glucose/`HbA1c`/`ALT`).
  - A newly verified genomic dataset uncovers clinically actionable pathogenic variants, or an upstream `ClinVar`/`CPIC` release reclassifies a patient's variant (`VUS -> Pathogenic`).
  - An active treatment conflicts with newly verified pharmacogenomic markers or logged adverse symptoms.
- **Time-Critical Escalation (`<4h` SLA):** Countdown tracking on unacknowledged urgent alerts before automated clinical escalation (`+4h` escalation timer).
- **Closed-Loop Triage Actions:** Acknowledging alerts, proposing preventive appointments (selecting date/time, in-person or WebRTC telehealth modality, consultation category, and specific pre-visit `LOINC` laboratory requisitions), and notifying the patient through `Zero-PHI` channels.

### 3.3 Consented Patient Roster & Rapid Clinical Intake
- Searching and filtering consented patients by name, risk severity, primary `ICD-10` diagnoses, genomic verification status, or pending laboratory results.
- Rapid registration of new patients, capturing baseline anthropometrics (`height`, `weight`, `waist circumference`, auto-calculated WHO `BMI`), blood pressure (auto-classified AHA/ESC stage), documented allergies/intolerances, multi-generation family medical pedigree (oncological, cardiovascular, metabolic, autoimmune, neurological), and diaspora sponsor linkage if applicable.

### 3.4 Universal 8-Family `LOINC` Biomarkers, `Lab2HPO` Phenotyping & Partner Lab Sync
- Recording, searching, and longitudinally analyzing quantitative laboratory observations across **8 universal `LOINC` physiological families** (including rapid access to high-frequency Venezuelan *Perfil 20* markers plus the complete international catalog):
  1. **Metabolic & Glycemic:** Fasting Glucose, `HbA1c`, Fasting Insulin, `HOMA-IR`, C-Peptide, Uric Acid.
  2. **Cardiovascular & Advanced Lipids:** Total Cholesterol, `HDL-C`, `LDL-C`, Triglycerides, `ApoB`, `Lp(a)`, `hs-CRP`, Homocysteine, `NT-proBNP`, Troponin, `CK`, Fibrinogen, D-Dimer.
  3. **Renal & Electrolytes:** Serum Creatinine, `eGFR`, Cystatin C, Urea/`BUN`, Urine Albumin-to-Creatinine Ratio (`uACR`), `Na+`, `K+`, `Cl-`, `Ca2+`, `Mg2+`, Phosphorus.
  4. **Hepatic & Pancreatic:** `ALT` (`TGP`), `AST` (`TGO`), `GGT`, `ALP`, Total/Direct Bilirubin, Albumin, Total Protein, Amylase, Lipase.
  5. **Hematology & Iron/Hemolysis:** Complete Blood Count (`CBC`), Serum Iron, Ferritin, Transferrin Saturation (`TSAT %`), `TIBC`, `LDH`, Haptoglobin, quantitative `G6PD` activity.
  6. **Endocrine & Hormones:** `TSH`, Free `T4`, Free `T3`, `Anti-TPO`, Cortisol, Estradiol, Testosterone, `LH`, `FSH`, Prolactin, `PTH`.
  7. **Vitamins, Minerals & Specialty Metabolism:** `25-OH Vitamin D`, Vitamin `B12`, Folate (`B9`), Omega-3 Index, Zinc, Copper, Ceruloplasmin.
  8. **Autoimmune, Inflammatory & Oncology Markers:** `Anti-tTG IgA`, `ANA`, `ESR`, `PSA`, `CA-125`, `CEA`, `AFP`, `CA 19-9`.
- **Person-Centric Biomarker Prioritization & Temporal Medication Context:** Highlighting analytes specifically critical for that patient's genotype (`LDLR` -> `ApoB`/`LDL-C`; `APOL1` -> `uACR`/Creatinine; `HFE` -> `TSAT %`/Ferritin; `SLCO1B1` -> `CK`), correlated over time with medication start/stop dates, `CALIPER`/`IFCC` sex/age reference thresholds, bidirectional `UCUM` unit normalization (`SI` $\leftrightarrow$ conventional), automated `Lab2HPO` ontology translation (`HP:...` terms), and inbound `HL7 FHIR R4` laboratory sync provenance (`externalAccessionId`, `SHA-256`).

### 3.5 Multi-Specialty Diagnostic Studies & Clinical `DICOM` Inspection
- Reviewing (and, when acting as a performing specialist physician, recording) consented diagnostic reports and structured quantitative specialty metrics across all 6 clinical domains:
  - *Genomics & Molecular:* Verified callset provenance, reference assembly, `DP`/`GQ`/`PASS` metrics.
  - *Bioanalysis & LIS:* Standardized `LOINC` observations and `HL7 FHIR R4` accession history (`NewlyIngested` vs. `IdempotentReplay`).
  - *Sonography & Doppler:* Hepatic steatosis grade (`0–III`), renal length (`mm`), Renal Resistive Index (`RI`), Left Ventricular Ejection Fraction `LVEF` (`%`).
  - *Radiology & `DICOM`:* `CT`, `MR`, `US`, `DX`, `CR` studies (`StudyInstanceUID`, series/instance counts, tissue window/level presets for lung/bone/soft-tissue/brain, zoom/pan, linear/ROI calipers).
  - *Cardiopulmonary:* Heart rate (`bpm`), `PR` / `QRS` / `QTc Bazett` (`ms`), rhythm classification, `ECG` waveforms, echocardiogram cine loops, spirometry `FEV1`/`FVC` (`% predicted`).
  - *Histopathology & Biopsy:* Biopsy site, `TNM` staging, surgical margin status, immunohistochemistry (`ER`, `PR`, `HER2`, `PD-L1 TPS`, `MSI`/`MMR`).

### 3.6 Eight-Pillar Clinical Decision Support (`CDSS`), `CIViC` Oncology, `PRS` & Endemic Tropical Triage
- Real-time evaluation and on-demand re-evaluation combining verified genotypes, `LOINC`/`HPO` biomarkers, vital signs, active medications, and clinical symptoms across **8 clinical genomic pillars**:
  1. **Hereditary Oncology & Somatic Actionability:** `BRCA1`, `BRCA2`, `PALB2`, `ATM`, `CHEK2`, Lynch (`MLH1`, `MSH2`, `MSH6`, `PMS2`), `APC` early surveillance protocols (10–15 years ahead of population average) and cascade family screening, plus somatic/targeted therapy and resistance evidence (`CIViC` / `AMP` tiers for `EGFR`, `KRAS`, `ALK`, etc.).
  2. **Pharmacogenomics (`PGx`) & Perioperative Safety:** `CYP2C19` (clopidogrel, PPIs, SSRIs), `SLCO1B1` (statin myopathy), `CYP2D6` (tamoxifen, opioids, antidepressants), `VKORC1`/`CYP2C9` (warfarin, NSAIDs), `DPYD` (fluoropyrimidine toxicity), `RYR1`/`CACNA1S` (malignant hyperthermia anesthesia avoidance), `G6PD`, `HLA-B*15:02`/`*57:01`/`*58:01`, `MT-RNR1`.
  3. **Monogenic Cardiology, Arrhythmias & Thrombophilia:** Familial hypercholesterolemia (`LDLR`, `APOB`, `PCSK9`), inherited cardiomyopathies and channelopathies (`MYBPC3`, `MYH7`, `KCNQ1`, `SCN5A`), and Factor V Leiden / Prothrombin thrombophilia (`F5`, `F2` — contraindicating estrogen therapy).
  4. **Autoimmune, `HLA` & Gastrointestinal Disorders:** Celiac disease (`HLA-DQ2.5`/`DQ8` + `Anti-tTG IgA`), `HLA-B27` spondyloarthropathy, `NOD2` IBD, `SERPINA1` alpha-1 antitrypsin deficiency, `MCM6`.
  5. **Cardiometabolic, Endocrine & Genetic Fatty Liver (`MASLD`):** `TCF7L2`, `FTO`, `MC4R`, `PPARG`, and `PNPLA3`/`TM6SF2` steatohepatitis/fibrosis interception (`HOMA-IR`, `HbA1c`, hepatic elastography).
  6. **Renal & Hypertensive Protection:** `APOL1` (`G1`/`G2` biallelic risk), `AGT`, `ACE`, `UMOD` glomerular protection (`ACEi`/`ARB` initiation, `uACR` + Cystatin C surveillance, NSAID avoidance).
  7. **Reproductive Carrier & Perinatal Medicine:** Recessive carrier status (`CFTR`, `SMN1`, `HBB`, `GJB2`, `PAH`, `MTHFR`), couple compatibility counseling, and targeted perinatal protocols.
  8. **Neurogenetics & Cognitive Longevity:** `APOE` ($\varepsilon2/\varepsilon3/\varepsilon4$) aggressive vascular/lipid prevention (`ApoB < 70 mg/dL`), `BDNF`, `COMT`, `LRRK2`, `GBA1`.
- **Ancestrally Calibrated `PRS` & Modifiable Risk Simulation:** Disease percentile risk plus projected 10-year risk reduction when clinical targets (`BP`, `BMI`, `LDL-C`, `HbA1c`) are achieved.
- **Endemic Tropical & Infectious Disease Triage:** Regional Venezuelan/LatAm host-genetics rules including `G6PD` hemolytic crisis blocking primaquine in malaria, `MICB`/`PLCE1` severe dengue shock warning protocols, `ACKR1`, and Chagas cardiac monitoring.
- **Mechanistic Genomic Knowledge & Panel Recommendations:** Access to rich variant-to-gene-to-condition-to-biomarker-to-medication knowledge (`MANE Select` `HGVS.c`/`HGVS.p`, `OMIM` IDs, `ACMG SF v3.2` secondary findings & `ACMG Tier 3` carrier flags, zygosity risk differentiation across `0/0`, `0/1`, `1/1`, compound heterozygous `1/2`, hemizygous, and homoplasmic `mtDNA`, `ClinVar` review stars `0–4`, `PharmGKB` / `CPIC` evidence tiers, mandatory post-prescription `LOINC` monitoring analytes, and `gnomAD`/`1000G` population allele frequencies), plus automated recommendations for targeted genetic panels (`MetabolicHepatic`, `CardioRenal`, `PharmacogenomicsSafety`, `CeliacGiNutrition`) when clinical phenotypes suggest unscreened hereditary causes.

### 3.7 Structured `SOAP` Encounters, Synchronous `PGx` Prescribing, Telehealth & Referrals
- **Structured `SOAP` Clinical Documentation:** Authoring and signing chronological encounter records containing:
  - *Subjective:* Chief complaints, symptom onset/severity/duration, and standardized `HPO` symptom terms.
  - *Objective:* Physical examination observations, vital signs, and key laboratory/imaging findings.
  - *Assessment:* Standardized `ICD-10` working and confirmed diagnoses.
  - *Plan:* Prescribed medications, diagnostic laboratory/imaging orders, personalized lifestyle targets, and follow-up timing, plus marking scheduled appointments as completed.
- **Hard-Stop Pharmacogenomic & Allergy Prescription Safety Gate:** Real-time validation of any candidate drug and dosage against the patient's verified `CPIC`/`HLA`/`MT-RNR1`/`G6PD` genotypes, documented allergies, and renal/hepatic biomarkers *before* a prescription is saved:
  - Classifies prescriptions as `Safe`, `Caution / Dose Adjustment`, or `Contraindicated`.
  - Explains whether an active drug accounts for a patient's refractory symptoms or adverse reactions (e.g., `SLCO1B1` statin myalgia) and proposes evidence-based therapeutic substitutions (e.g., `Simvastatin -> Rosuvastatin`, `Clopidogrel -> Prasugrel`).
  - Blocks `Contraindicated` prescriptions unless the physician records an explicit signed clinical override rationale, and tracks longitudinal therapeutic response (`Effective`, `Partial`, `Refractory`, `AdverseReaction`).
- **Zero-Trust `WebRTC` Telehealth Consultations:** Launching encrypted remote consultations for `Confirmed` appointments using `900-second` `HMAC-SHA256` participant tokens, reviewing biomarkers and `DICOM` imaging live with the patient while documenting `SOAP` notes and prescriptions, with immediate automatic session termination if the patient revokes sovereign consent.
- **Inter-Specialty Referrals:** Initiating formal referrals to specialists or partner clinics specifying clinical rationale and required medical record compartments (held pending sovereign patient approval, with `SelfReferralConflict` enforcement).
- **Physician Boundaries:** Physicians cannot access unconsented patient records, cannot treat or refer themselves (`SelfTreatmentProhibited` / `SelfReferralConflict`), cannot clinically verify or reject raw sequencing datasets (`ClinicalVerifier` exclusive duty), cannot confirm appointments on a patient's behalf, and do not manage partner laboratory wholesale billing or platform-wide user/organization administration.

---

## 4. Administrator Capabilities (Clinical Operations Director, Credentialing Officer & Platform Governance)

### 4.1 Acting Contexts & Clinical Operations Scope
- **Hospital / Clinic Operations Director & Platform Governance Officer:** The Administrator manages multi-clinic healthcare operations, medical specialty capacity, follow-up adherence, professional licensing, organization boundaries, biomedical catalog integrity, commercial settlement/messaging pipelines, and zero-trust security compliance—**strictly separated from private patient clinical content (`PHI`)**.
- **Three Operational Focus Contexts:**
  1. **Clinical Operations & Retention:** Tracking patient volume, specialty backlog, turnaround SLA compliance, and follow-up adherence across solo practices and multi-specialty clinics.
  2. **Credentialing & Organization Governance:** Verifying, onboarding, updating, and suspending multi-role professional accounts and healthcare organizations (`SoloPracticeFirm` vs. `MultiSpecialtyClinic`).
  3. **Platform Integrity, Catalogs & Zero-Trust Compliance:** Auditing the 9 biomedical knowledge-base sync pipelines, payment/webhook settlement and Zero-PHI messaging queues, multi-tier API rate-limit quotas, and immutable security/conflict-of-interest audit logs.

### 4.2 Patient Volume, Diagnostic Turnaround (`TAT`), Specialty Matrix & Doctor Workload
- **Patient Treatment Volume & Visit Breakdown:** Real-time operational metrics filtered by time window (**`Today`**, **`Last 7 Days`**, **`Last 30 Days`**, or custom quarter), organization type (`SoloPracticeFirm` vs. `MultiSpecialtyClinic`), and medical specialty—comparing volume against rolling daily averages across four visit types:
  1. **New Patient Consultations**
  2. **Return Preventive Follow-Up Visits**
  3. **`<48h` Rapid Exam Readings** (*Lectura de Exámenes*)
  4. **Urgent CDSS Alert Interventions** (`<4h` triage response)
- **End-to-End Diagnostic & Verification Turnaround Time (`TAT`):** Tracking elapsed latency from `Sample Collection` $\rightarrow$ `Lab Upload` $\rightarrow$ `Clinical Verifier Sign-Off` $\rightarrow$ `Doctor Consultation`, including `% meeting <48h SLA` and `<4h` urgent CDSS alert acknowledgment compliance.
- **Cases by Medical Specialty Matrix:** Operational demand, completed cases, open backlog, and SLA adherence across the **6 core medical specialties**:
  1. Cardiology & Vascular Medicine
  2. Internal Medicine & Primary Prevention
  3. Endocrinology, Diabetes & Metabolism
  4. Nephrology & Hypertension
  5. Medical Oncology & Hereditary Cancer
  6. Clinical Genetics & Pharmacogenomics
- **Per-Doctor Operational Case Roster:** Inspecting each physician's license ID (`MPPS`), primary/secondary specialties, affiliated clinic(s), cases reviewed (`Today / 7d / 30d` broken down by specialty), active open consultation slots, pending clinic-queue claims, and average consultation turnaround time—drilling down into timestamped operational activity counts without exposing private `SOAP` clinical text.

### 4.3 Follow-Up Appointment Adherence, Retention & Zero-PHI Outreach
- **Follow-Up Attendance & Drop-Off Analytics:** Measuring on-time follow-up attendance rate (`%`) versus **Overdue Follow-Ups**, **Rescheduled Visits**, and **No-Shows** across specialties and clinics, identifying where patients drop off after an initial high-risk finding.
- **Batch Zero-PHI Reminder Campaigns:** Triggering privacy-safe (`Zero-PHI`) follow-up reminder batches (`WhatsApp Business`, `Transactional Email`, `WebPush`) for overdue patient cohorts (using background `24h`/`7d` appointment reminder schedules without including genotypes, `rs` IDs, or diagnoses in external messages).

### 4.4 Professional Identity & 6-Role Credential Governance
- **Multi-Role Credential Desk:** Reviewing, verifying, approving, updating, and suspending accounts across all **6 platform roles** (`PATIENT`, `DOCTOR`, `CLINICAL_VERIFIER`, `LAB_TECH`, `RESEARCHER`, `ADMIN`):
  - **Doctors:** `MPPS` medical license number (`medical_license_mpps`), medical college registration, and specialty board certifications.
  - **Clinical Verifiers:** Molecular genetics / pathology board certification (`ACMG`, `EBMG`, `SVGH`) and accrediting institution.
  - **Laboratory Technicians:** Technical board registry (`FEVIBI`/equivalent), partner laboratory affiliation, and strict assignment to 1 of the **6 accredited diagnostic specialties** (`Genomics`, `Bioanalysis`, `Sonography`, `Radiology`, `Cardiopulmonary`, `Histopathology`).
  - **Researchers:** Institutional affiliation, `ORCID` identifier, and active bioethics / `CENABI-IRB` protocol approval code.
- **Multi-Role Assignment & Emergency Revocation:** Managing valid multi-role combinations (e.g., `PATIENT + DOCTOR`, `DOCTOR + RESEARCHER`) while preserving separation-of-duties invariants, and executing **Emergency Credential Suspension & Instant `900s` Session Revocation**.

### 4.5 Healthcare Organization Registry & Capacity Management
- **Organization Lifecycle & Tax/Sanitary Compliance:** Registering and managing organizations with Venezuelan tax ID (*RIF* `tax_id_rif`), sanitary permit validation, specialty coverage, open consultation slot capacity, and active staff affiliation:
  - **`SoloPracticeFirm`:** Independent physician office strictly constrained to **1 active doctor** (`SoloFirmSingleMemberLimit` enforced on every membership action).
  - **`MultiSpecialtyClinic`:** Hospital, polyclinic, or partner diagnostic center supporting multiple physicians, multi-specialty clinic queues, `<48h` reading pools, and specialized lab technicians.
- **Clinic Preventive Retention Metrics:** Tracking active patient base, preventive consultations generated, and repeat diagnostic orders per clinic.

### 4.6 Biomedical Knowledge Base Synchronization (9 Official Catalogs)
- **9-Source Catalog Health & Manifest Integrity:** Auditing sync state, active release versions, `SHA-256`/`ETag` checksums, staleness SLA status, last sync timestamps, event-stream lag, and total indexed records across all **9 biomedical catalogs**:
  1. `ClinVar`
  2. `Ensembl VEP / MANE Select`
  3. `CPIC / PharmGKB`
  4. `LOINC`
  5. `HPO / Lab2HPO`
  6. `CALIPER / IFCC`
  7. `gnomAD v4`
  8. `PGS Catalog`
  9. `CIViC`
- **Sync Operations:** Triggering confirmed on-demand catalog synchronization runs and auditing periodic automated sync schedules (`scraper-service` $\rightarrow$ `catalog` event stream).

### 4.7 Commercial Settlement Pipelines & Zero-PHI Messaging Delivery Ops
- **Multi-Rail Payment & B2B Settlement Monitoring:** Auditing platform payment lifecycles (`PendingCheckout` -> `Authorized` -> `Settled` | `Failed` | `Refunded`) across **Cashea `0%` APR Split-Installments** (`>= $20.00 USD`, `{40%, 50%, 60%}` initial + 3 biweekly installments), **`Stripe USD`**, **`Crypto USDT`**, and **`Partner Clinic Invoice USD`**, including webhook signature validation / replay rejections and **B2B Partner Lab Wholesale Billing** (`$10–$30 USD` strictly gated on `ClinicallyVerified` datasets).
- **Zero-PHI Notification Queue & Dead-Letter Recovery:** Monitoring delivery receipts across `WhatsApp Business`, `Transactional Email`, and `WebPush` (`Delivered`, `Retrying 1–4`, `Dead-Lettered >= 5`), re-driving failed deliveries, and verifying a continuous `0` PHI leakage enforcement score.

### 4.8 Zero-Trust Security Audit, Rate-Limit Quota Governance & Administrator Boundaries
- **Immutable Hash-Chained Security & CoI Audit Ledger:** Searching and filtering append-only audit logs by actor, role, decision (`ALLOW` vs. `DENY`), date range, or specific security/separation-of-duties rule (`SelfTreatmentProhibited`, `SelfReferralConflict`, `SelfVerificationProhibited`, `SelfDiagnosticUploadProhibited`, `UnauthorizedDiagnosticCategoryForSpecialty`, `KAnonymityThresholdViolation`, `SoloFirmSingleMemberLimit`, OAuth 2.1 `(Actor ∩ Subject)` token exchange, and WebAuthn Passkey revocations), with compliance export.
- **Distributed Rate-Limiting & Multi-Tier Quota Governance:** Auditing real-time quota consumption and throttle events across the **5 API quota tiers** (`PublicAnonymous 10 rpm`, `StandardUser 300 rpm`, `ClinicalSpecialist 600 rpm`, `PartnerLabTenant 1,200 rpm`, `InternalWorkload 5,000 rpm`) and weighted genomic operations (`VcfUpload` weight `10`, `ClinicalReportExport` weight `5`, `AppointmentBooking` weight `2`).
- **Administrator Boundaries (What the Administrator Cannot See or Do):**
  - **Zero Private `PHI` or Genomic Variant Access:** Administrators see operational counts, specialty case volumes, appointment statuses, turnaround times, and security metadata—they **never** read private patient `SOAP` consultation notes, raw `VCF`/`BCF` variants, individual genomic risk scores, or personal diagnostic reports/images.
  - **No Clinical Sign-Off or Medical Authoring:** Administrators cannot clinically verify or reject sequencing datasets (`ClinicalVerifier` exclusive duty), cannot upload or certify diagnostic test results (`LAB_TECH` exclusive duty), and cannot author `ICD-10` diagnoses or medical prescriptions (`DOCTOR` exclusive duty).
  - **Zero Mutation of Immutable Records:** Administrators cannot alter, backdate, or delete cryptographic dataset `SHA-256` seals or append-only hash-chained security audit logs.

---

> **UI Design Direction Note (`doctor-04`):** Among the generated UI iterations, `doctor-04/` (`design-taste-frontend-v1`) has the cleanest UI model and is recommended as the base style (buttons, controls, and overall component styling) for future UI work.