Architecture, Glossary & Deep-Dives

1. High-Level Architecture #

REV.health is two co-deployed static sites — a top-down walkthrough for clinical decision-makers and an interactive 6-persona demo — backed by a shared 4-theme design system and a single LocalStorage state graph.

The walkthrough (this site, docs/prd-v2/) is pure HTML/CSS/JS with no frameworks and no server. Pages are organized as a five-level hierarchy: L0 Pitch → L1 Personas → L2 Modules → L3 Patient Journey → L4 Reference. A shared shell (header, sidebar, footer) is injected at runtime by shell.js. Global search is powered by a pre-built Lunr.js index; a per-page filter highlights inline matches. Theme persistence travels through rev-demo-theme in LocalStorage so both sites stay in sync on the same origin.

The demo app (docs/demo/) is also static HTML, but each persona dashboard reads from and writes to a single JSON document in rev-demo-state. All mutations go through a central reducer that validates the action, applies the change immutably, stamps an audit-log entry, and writes back. Actions in one persona's view propagate to other personas' queues so the reader experiences the cross-functional flow without leaving the browser.

Both sites share identical CSS custom-property token names (--color-bg, --color-text, --color-accent, etc.) so a component built for one site renders identically on the other. Four themes — Light, Dark, Hospital, Modern — swap purely by changing the body class.

The production architecture behind the PRD is FHIR-native (US Core 7.0.0+), AI-native (ambient scribe + CDS Hooks 2.0), TEFCA-connected at launch, multi-tenant, and active-active. Every module ships as an icApplication generated from AMI schemas on the IC platform — forms, state machines, validation, RBAC, audit, and FHIR bindings are derived once from the schema rather than re-implemented per screen. The database is a dumb store; the API enforces every relationship; the front end is generated, not hand-built.

2. Glossary #

Key terms used across the walkthrough. Each entry has a stable id so any page can link to reference.html#glossary-term.

AAL2

Authenticator Assurance Level 2 (NIST 800-63-3). Two-factor authentication where one factor is a possession-based device. Required for clinical workflows and EPCS signing.

ACO

Accountable Care Organization. Group of clinicians and hospitals accountable for the cost and quality of care for a defined population, typically Medicare beneficiaries.

ADT

Admit, Discharge, Transfer. The traditional HL7 v2 message family for patient state changes. REV.health is ambulatory-first and does not implement ADT-driven inpatient workflows.

AMI

Application Model Information. The IC platform's schema definition of a noun-app — entity, fields, types, primary key, foreign keys, audit fields. AMI is the input to code generation; every REV.health module is composed of noun-apps generated from AMI schemas.

AMA

American Medical Association. Owner and maintainer of CPT codes. Releases an annual update each January 1; the CY2026 release introduced the first AI-augmented CPT codes.

APM

Alternative Payment Model. Non-fee-for-service Medicare payment models, including Advanced APMs that qualify clinicians out of MIPS.

AVS

After-Visit Summary. The patient-facing handout summarizing diagnoses, medications, and follow-up instructions. REV.health auto-generates a plain-language version at configurable reading level and offers translation.

BAA

Business Associate Agreement. The HIPAA contract that binds a vendor handling PHI on behalf of a covered entity. Every REV.health sub-processor signs one.

Bulk FHIR

Population-scale FHIR data export specification ($export operation per Bulk Data v2.0.0).

C-CDA

Consolidated Clinical Document Architecture. HL7 XML document standard for transitions of care. C-CDA R4.1 Companion Guide required from Jan 1, 2026.

CancelRx

NCPDP SCRIPT message that cancels a previously sent prescription. One of the SCRIPT 2017071 messages REV.health implements.

CARC / RARC

Claim Adjustment Reason Codes / Remittance Advice Remark Codes. Standardized reason codes returned on an X12 835 explaining adjustments and denials.

CareRelationship

REV.health org-scoped linking entity that connects a global Patient to an Organization. Expresses the practice-patient relationship without making the patient an org-owned entity.

CDS Hooks

Specification for invoking external clinical decision support at workflow trigger points. REV.health implements CDS Hooks 2.0 at orders-sign, patient-view, and encounter-discharge.

CMS

Centers for Medicare & Medicaid Services. The federal agency that administers Medicare, Medicaid, CHIP, and the Federally Facilitated Exchange. Sets the rules that drive about 40% of US healthcare spending.

CMS-0057-F

CMS Final Rule mandating Patient Access, Provider Access, Payer-to-Payer, and Prior Authorization FHIR APIs for impacted payers by January 1, 2027. Forces 72-hour expedited and 7-day standard prior-authorization decisions.

COB

Coordination of Benefits. Rules determining which payer pays first when a patient has multiple coverages.

CPT

Current Procedural Terminology. Procedure codes maintained by the AMA. ~10,000 codes. Annual release each January 1; CY2026 introduced AI-augmented CPT codes.

CSP

Credential Service Provider. NIST term for an entity that proofs identity and issues credentials. ID.me is the CSP for IAL2 EPCS onboarding.

Da Vinci

HL7 accelerator producing payer/provider FHIR Implementation Guides: PAS, CRD, DTR, CDex, PDex.

DDI

Drug-Drug Interaction. One of four required drug checks (DDI, drug-allergy, drug-disease, dose range) per HTI-1 §170.315(b)(11).

DEA EPCS

The DEA's electronic-prescribing-of-controlled-substances rule, 21 CFR 1311. Requires IAL2, AAL2, FIPS 140-2 hard tokens, digital signatures, and Drummond third-party app cert.

DICOM / DICOMweb

Digital Imaging and Communications in Medicine. The medical-imaging standard. DICOMweb is the REST-based flavor used for Ambra / PowerShare / Life Image integrations.

Direct Trust

Secure email-style transport for clinical messages. Used by REV.health Referrals as a fallback/parallel path to TEFCA. A HISP acts as the trust anchor.

Drummond Group

ONC-Authorized Certification Body for §170.315 EHR certification. Also performs DEA EPCS app certification.

DSI

Decision Support Intervention. HTI-1's name for AI/ML-driven clinical recommendations. Subject to algorithm-transparency requirements: model card, training data, performance metrics, biases, drift monitoring.

E/M

Evaluation & Management codes (CPT 99202–99499). 2021/2023 guidelines made selection MDM- or time-based. REV.health surfaces E/M level prediction with rationale.

EHR

Electronic Health Record. The clinical record system.

EMR

Electronic Medical Record. Originally distinguished from EHR (single-org vs. interoperable), now functionally synonymous.

EOB

Explanation of Benefits. The human-readable form of an X12 835 sent to patients.

EPCS

Electronic Prescribing of Controlled Substances. Governed by DEA 21 CFR 1311. Requires IAL2 identity proofing, AAL2 two-factor, FIPS 140-2 hard tokens, and Drummond third-party app certification.

ePA

Electronic Prior Authorization. NCPDP SCRIPT-based prescription prior auth, native via Surescripts.

ERA

Electronic Remittance Advice. Synonymous with X12 835.

FCA

False Claims Act. Treble damages plus per-claim penalties for knowingly false Medicare/Medicaid claims. Drives strict guardrails on the Payer Optimization module.

FCRA

Fair Credit Reporting Act. Governs credit checks; permissible-purpose required.

FHIR

Fast Healthcare Interoperability Resources. The HL7-maintained REST/JSON standard for healthcare data exchange. R4 is the regulated baseline; REV.health is FHIR-native via US Core 7.0.0+.

FIDO2 / WebAuthn

Phishing-resistant authentication standards. Preferred MFA second factor in REV.health.

Formulary

A payer's list of covered drugs and tiers. RTPB queries surface formulary status at the prescribe step.

GFE

Good Faith Estimate. Required by the No Surprises Act for self-pay patients ahead of scheduled services.

gRPC

Google's RPC framework over HTTP/2 with Protobuf. Used for REV.health internal service-to-service communication.

HCC / RAF

Hierarchical Condition Categories / Risk Adjustment Factor. CMS risk-adjustment model; REV.health surfaces HCC capture hints with strict clinician confirmation.

HCPCS Level II

CMS-maintained codes for DME, drugs, supplies, ambulance. Quarterly updates.

HIE / HIN

Health Information Exchange / Health Information Network. Pre-TEFCA regional networks merging into TEFCA.

HIPAA

Health Insurance Portability and Accountability Act of 1996. Title II governs PHI, BAAs, the 18 PHI identifiers, the Security Rule, and the Breach Notification Rule. Security Rule final rule update expected May 2026.

HITECH

Health Information Technology for Economic and Clinical Health Act (2009). Drove EHR adoption via Meaningful Use; expanded HIPAA enforcement to business associates.

HITRUST CSF

Health Information Trust Alliance Common Security Framework. Three certification tiers: e1, i1, r2. REV.health targets i1 in P2+ post-launch.

HL7 v2

HL7 messaging standard using pipe-and-hat delimited segments. Still 80%+ of real-world clinical interfaces. REV.health speaks v2 for labs (ORU/OML), devices, and immunization registries.

HPI / ROS / PE

History of Present Illness / Review of Systems / Physical Exam. Standard SOAP note sections.

HTI-1

ONC HTI-1 Final Rule. Sets the USCDI v3 baseline, revises 30+ §170.315 certification criteria, establishes the DSI transparency framework. Effective January 1, 2026 with enforcement discretion through March 1, 2026.

HTI-2

Follow-on ruleset focused on payer-side interoperability and public-health reporting. Tracking; absorb at low marginal cost given FHIR-native architecture.

HTI-3

Further extensions of DSI transparency and information-blocking exception handling. Tracking.

HTI-4

FY2026 IPPS rule introducing certification criteria for ePA, eRx modernization, and RTPB. Native via Surescripts.

IAL2

Identity Assurance Level 2 (NIST 800-63-3). Identity proofing required for EPCS clinician onboarding. ID.me is the contracted CSP.

IC (Infinite Cabinet)

The platform REV.health is generated on top of. IC takes AMI definitions and produces DB → API → Components → Deploy. Has 14 hard rules; see IC Rules Reference below.

ICD-10-CM

International Classification of Diseases, 10th revision, Clinical Modification. ~73,000 diagnosis codes. Annual update October 1.

icApplication

An application generated end-to-end from an AMI schema on the IC platform. Database, API, UI components, state machines, validation, RBAC, and FHIR bindings are derived once from the schema rather than re-implemented per screen.

IIS

Immunization Information System. State/jurisdictional registries; HL7 v2 VXU is the common transport.

KLAS

Independent vendor-rating firm whose research carries weight with healthcare buyers, particularly hospitals and large groups.

KMS / HSM

Key Management Service / Hardware Security Module. REV.health uses per-tenant KMS keys (AWS KMS) for tenant-isolated encryption.

Kno2

QHIN sub-participant network favored by small EHR vendors. REV.health's primary TEFCA on-ramp at launch.

LCD / NCD

Local / National Coverage Determinations. CMS coverage policies that drive claim scrubbing rules.

LOINC

Logical Observation Identifiers Names and Codes. Standard codes for lab tests and observations.

MACRA

Medicare Access and CHIP Reauthorization Act of 2015. Created the Quality Payment Program with MIPS and Advanced APMs.

MDM

Medical Decision Making. The driver of E/M code selection under 2021/2023 guidelines.

MHX

Medication History exchange. NCPDP SCRIPT message that retrieves a patient's dispensing history from PBMs and pharmacies.

MIPS

Merit-based Incentive Payment System. CY2026 weights: Promoting Interoperability 25 / Quality 30 / Improvement Activities 15 / Cost 30. ±9% Medicare adjustment two years after the performance year.

Modifier

A two-character CPT addendum that further specifies a procedure (e.g., -25 significant separate E/M, -59 distinct procedural service, -95 telehealth).

MUE

Medically Unlikely Edit. CMS-published per-day-per-CPT maximums used in claim scrubbing.

NCCI

National Correct Coding Initiative. CMS edits that flag CPT pairs that should not be billed together.

NCPDP SCRIPT

National Council for Prescription Drug Programs SCRIPT standard. Pharmacy industry eRx messaging; REV.health implements 2017071.

NDC

National Drug Code. FDA's package-level drug identifier.

No Surprises Act

Federal law (2020, effective 2022) banning balance billing for emergency services and certain OON situations; requires Good Faith Estimates for self-pay scheduled services.

Noun-App

The IC term for a single-entity AMI definition that is generated end-to-end (DB → API → Components). REV.health's modules are composed of dozens of noun-apps.

NPI

National Provider Identifier. 10-digit CMS-issued identifier used on claims.

NPPES

National Plan and Provider Enumeration System. The CMS public NPI registry. REV.health uses NPPES for specialist directory lookups.

OCR (HHS)

HHS Office for Civil Rights. Enforces HIPAA Privacy and Security Rules; investigates breaches.

OCR (insurance card)

Optical Character Recognition applied to a photographed insurance card to populate a structured Coverage record automatically.

ONC / ASTP

Office of the National Coordinator for Health IT (renamed ASTP July 2024). Runs §170.315 EHR certification.

Org

The IC term for an organization tenant. REV.health Orgs are practices. Most entities (Encounter, Claim, Coverage, etc.) carry an OrgID per IC Rule 11; User and clinical facts are exceptions.

42 CFR Part 2

Federal protection for substance-use-disorder treatment records. 2024 SAMHSA Final Rule (compliance Feb 16, 2026) aligns Part 2 with HIPAA for TPO but retains consent and redisclosure rules.

Pajama time

The two to three hours of after-hours charting most primary care physicians do nightly. Eliminating it is a north-star metric for REV.health (provider hours saved/day ≥ 1.5).

PBM

Pharmacy Benefit Manager. Express Scripts, CVS Caremark, OptumRx are the largest. RTPB queries terminate at PBMs.

PDMP

Prescription Drug Monitoring Program. State-by-state controlled-substance dispensing registries. REV.health integrates PDMP queries at the prescribe step for EPCS workflows.

PHI

Protected Health Information. The HIPAA-defined set of identifiable health data. The 18 PHI identifiers are listed in 45 CFR §164.514(b)(2).

PMR

Patient Medical Record. The REV.health module that stores the longitudinal global clinical record across orgs.

Prior Authorization

Payer pre-approval required for certain procedures, drugs, or services. CMS-0057-F mandates 72-hour expedited and 7-day standard decisions for impacted payers from January 2027.

QHIN

Qualified Health Information Network. The top-tier hub in the TEFCA hub-and-spoke model. 11 designated QHINs as of 2026; REV.health connects as a sub-participant under Kno2.

QPP

Quality Payment Program. CMS umbrella that contains MIPS and Advanced APMs.

RBAC

Role-Based Access Control. REV.health combines RBAC for coarse roles with ABAC for fine-grained context (which patient, which encounter, which authorization chain).

RCM

Revenue Cycle Management. Charge capture → coding → scrubbing → claim submission (837P) → remittance posting (835 ERA) → denials/appeals → patient billing → collections.

Rooming

The MA workflow of placing the patient in an exam room and capturing chief complaint, vitals, screenings, and immunization due-list. REV.health surfaces a single rooming view to eliminate tab-switching.

RTPB

Real-Time Prescription Benefit. NCPDP transaction that returns patient-specific cost and formulary status at the prescribe step.

RxNorm

NLM-maintained normalized vocabulary for drugs. Used for medication coding and allergy mapping.

RVU

Relative Value Unit. The CMS work / practice-expense / malpractice unit that drives Medicare physician fee schedules.

S3 / Object Lock

AWS Simple Storage Service with WORM Object Lock. REV.health stores PHI documents and the append-only audit log here with Object Lock retention.

Short GUID

REV.health convention: case-sensitive Base62 encoding of the full 128-bit GUID v4 → ~22 character identifier. Deterministic, reversible, no lookup table. Used for PKs/FKs in URLs and human-readable identifiers.

SMART on FHIR

OAuth 2.0 framework for FHIR apps. v2.2.0 with granular scopes is implemented in REV.health.

SNOMED-CT

Systematized Nomenclature of Medicine — Clinical Terms. ~350,000 clinical concepts; US Edition is the certified standard for problem-list coding.

SOC 2 Type II

AICPA audit attestation across the Trust Services Criteria. Type I at P1, Type II by launch.

SOAP / APSO

Subjective / Objective / Assessment / Plan — the traditional clinical note structure. APSO reverses the order (Assessment-Plan-Subjective-Objective) for faster reads by the signing clinician.

Surescripts

Dominant US eRx network — about 95% of US dispensing. Non-substitutable for at-scale prescribing. REV.health certifies directly; DrFirst is contracted as standby.

SVAP

Standards Version Advancement Process. ONC mechanism for adopting a newer standard version without re-certifying from scratch.

TCPA

Telephone Consumer Protection Act of 1991. Governs SMS, voice, and prerecorded-message consent. Per-message statutory damages drive strict opt-in/opt-out tracking.

TEFCA

Trusted Exchange Framework and Common Agreement. The federal hub-and-spoke health information exchange model. Common Agreement v2 is in force; REV.health connects as a QHIN sub-participant.

Terms of Care (ToC)

REV.health-specific document that governs who is authorized to see what part of a patient's record and why. Distinct from Terms of Service, which governs commercial service terms.

Terms of Service (ToS)

The commercial terms of service for REV.health, covering data ownership, patient rights, HIPAA privacy commitments, 42 CFR Part 2 sensitive-data handling, retention, dispute resolution, SLA commitments.

Trust Tier

REV.health provenance grading: Tier 0 user-asserted, Tier 1 patient-portal-confirmed, Tier 2 internal-clinician-recorded, Tier 3 externally-attested. Drives conflict resolution and display ranking.

USCDI

US Core Data for Interoperability. The standardized list of clinical data elements every certified EHR must support. v3 mandatory January 1, 2026; v4/v5 advance through the SVAP mechanism.

US Core IG

The HL7 US Core Implementation Guide that profiles FHIR R4 for US use. REV.health ships US Core 7.0.0 minimum at launch.

VBC

Value-Based Care. Pay-for-outcomes contract models, including ACO REACH and MSSP.

VDT

View, Download, Transmit. The 2014-edition criterion for patient access; later subsumed into §170.315(e)(1). Cures Act FHIR Patient Access supersedes much of it, but VDT remains the compliance shorthand.

WCAG 2.2 AA

Web Content Accessibility Guidelines 2.2, Level AA. The de facto digital accessibility target. axe-core gates every release.

WebAuthn

The W3C standard for FIDO2 public-key authentication in browsers. Preferred MFA second factor in REV.health.

X12 270/271

Eligibility request (270) and response (271). Sent in real time by REV.health at scheduling, 24h prior, and at check-in.

X12 275

Patient information / claim attachment.

X12 276/277

Claim status request / response.

X12 278

Health-care services review (prior authorization request).

X12 835

Electronic Remittance Advice. Auto-posted by REV.health with reason-code-driven exceptions.

X12 837

Health-care claim. 837P = professional, 837I = institutional, 837D = dental. REV.health submits 837P primarily.

X12 999 / 277CA

Functional acknowledgment / claims acknowledgment.

3. Regulatory Matrix #

Fifteen regulations and frameworks shape what REV.health must build, certify, and continuously prove. Each row states the requirement and the platform's delivery posture.

The deep-dives below expand each row of the summary matrix into its full requirement and the platform's delivery posture.

1. HTI-1 — ONC Final Rule (Health Data, Technology, and Interoperability) #

Description. The ONC HTI-1 Final Rule sets the USCDI v3 baseline for certified health IT, revises 30+ §170.315 certification criteria, and establishes the Decision Support Intervention transparency framework with model cards, training-data disclosures, performance metrics, and bias surveillance. Effective January 1, 2026 with enforcement discretion through March 1, 2026. Required for any EHR sold into Medicare-accepting practices via the MIPS Promoting Interoperability category.

REV.health relevance. Drummond Group certification against §170.315 is a hard prerequisite for launch. The platform delivers USCDI v3 via FHIR R4 with the US Core IG, ships SMART on FHIR v2.2.0 and Bulk Data v2.0.0, exposes CDS Hooks 2.0, and produces DSI model cards for every AI-driven recommendation surface (coding, scribe, denial prediction, scheduling).

2. HTI-2 — Public Health and Payer Interoperability #

Description. The follow-on HTI-2 ruleset focuses on payer-side interoperability and public-health reporting. It refines and extends API obligations, layering on top of HTI-1 rather than replacing it.

REV.health relevance. Because the platform is FHIR-first from day one, the marginal cost to absorb HTI-2 conformance is small. Public-health reporting (immunization, electronic case reporting, syndromic surveillance) is supported via standard FHIR profiles and HL7 v2 fallback for state agencies that have not yet modernized.

3. HTI-3 — Algorithm Transparency & Information Sharing #

Description. HTI-3 expands the DSI transparency obligations introduced in HTI-1 and tightens information-blocking exception handling. It pushes toward greater visibility into AI-driven decision surfaces and the upstream data pipelines that feed them.

REV.health relevance. Every AI-driven feature ships a model card and a lineage record. The platform maintains drift-monitoring dashboards by tenant and by clinical domain. Information-blocking exception decisions (preventing harm, privacy, security, infeasibility, content and manner, fees, licensing, health IT performance) are captured as structured records, not free text — see Contract Topology.

4. HTI-4 — Electronic Prior Auth, eRx, and RTPB #

Description. HTI-4 (FY2026 IPPS rule) introduces certification criteria for electronic prior authorization, electronic prescribing modernization, and Real-Time Prescription Benefit. These requirements push the rest of the industry toward what Surescripts already supports.

REV.health relevance. Native via the eRx / EPCS module. RTPB queries surface patient-specific cost at prescribe time, ePA via Surescripts handles the pre-auth workflow, and the eRx pipeline implements NCPDP SCRIPT 2017071 with full HTI-4 conformance test coverage.

5. USCDI v3 / v5 — US Core Data for Interoperability #

Description. The standardized list of clinical data elements every certified EHR must support. v3 is mandatory January 1, 2026; v4 and v5 advance through the SVAP process. v3 covers patient demographics, problems, allergies, medications, procedures, lab results, vital signs, immunizations, clinical notes, and care plans, plus social determinants and health-status assessments added in HTI-1 §170.315(a)(15).

REV.health relevance. v3 is the launch baseline. v5 (SVAP) is targeted post-launch, taking advantage of US Core 8.0.1 once available. The platform exposes USCDI through FHIR R4 with US Core 7.0.0 minimum at launch.

6. CMS-0057-F — Patient, Provider, Payer-to-Payer, and Prior Auth APIs #

Description. CMS Final Rule mandating four FHIR APIs for impacted payers (Medicare Advantage, Medicaid FFS/MCO, CHIP, Federally Facilitated Exchange QHPs) by January 1, 2027: Patient Access, Provider Access, Payer-to-Payer, and Prior Authorization. Forces 72-hour expedited and 7-day standard PA decisions and requires public reporting of metrics.

REV.health relevance. The platform is the provider side, not a payer, so the obligation is to be a high-quality client. The Eligibility module consumes the Da Vinci PAS / CRD / DTR / CDex APIs at the point of order entry, and the Task Management module consumes Provider Access notifications to keep encounter context current.

7. TEFCA / Common Agreement v2 #

Description. The Trusted Exchange Framework and Common Agreement is the federal hub-and-spoke model for nationwide health information exchange. By 2026 there are 11 designated QHINs covering more than 10,600 organizations. Common Agreement v2 introduces the FHIR Implementation SOP and tightens identity and security controls.

REV.health relevance. The platform connects as a QHIN sub-participant under Kno2 at launch (eHealth Exchange and Surescripts QHIN are evaluated as alternatives). One TEFCA pipe replaces dozens of hand-rolled integrations with hospitals, labs, and competing networks.

8. 42 CFR Part 2 — Substance Use Disorder Records #

Description. Federal protection for records originating from a federally assisted SUD treatment program. The 2024 SAMHSA Final Rule (compliance February 16, 2026) aligns Part 2 with HIPAA for treatment, payment, and operations purposes but retains the patient-consent requirement and adds explicit redisclosure rules.

REV.health relevance. Part 2 data is stored in a segmented compartment with an explicit consent record per disclosure, a redisclosure-tracking ledger, and a UX model that prevents accidental commingling. The data ownership model treats Part 2 attributes as a sensitivity label that propagates through the FHIR API and the patient portal.

9. DEA EPCS — 21 CFR 1311 #

Description. The DEA's electronic prescribing rule for controlled substances. Requires IAL2 identity proofing, AAL2 two-factor authentication at signing, FIPS 140-2 hard tokens, digital signatures on the prescription, and third-party application certification (Drummond Group or SLI Compliance). Mandated for Medicare Part D Schedule II–V by the SUPPORT Act.

REV.health relevance. ID.me as the IAL2 Credential Service Provider; FIDO2/WebAuthn or YubiKey as the AAL2 second factor; Drummond third-party application certification kicked off in P0 because it is on the critical path. The eRx / EPCS module implements digital signature, audit log, and PDMP query gating per state.

10. MIPS / MACRA — Quality Payment Program #

Description. Performance-based Medicare reimbursement adjustment created by MACRA. CY2026 weights: Promoting Interoperability 25%, Quality 30%, Improvement Activities 15%, Cost 30%. 75-point performance threshold; 27 MIPS Value Pathways available. ±9% Medicare adjustment two years after the performance year.

REV.health relevance. Native MIPS dashboards across all four categories, with the Quality category powered by an internal eCQM engine. Promoting Interoperability scoring is computed from the same telemetry that drives ONC §170.315(g)(10) conformance, so attestation is a one-click confirmation rather than a year-end scramble.

11. HIPAA — Privacy / Security / Breach Notification #

Description. The Health Insurance Portability and Accountability Act of 1996, as amended by HITECH (2009). Title II governs PHI, BAAs, the 18 PHI identifiers, the Security Rule (administrative, physical, and technical safeguards), and the Breach Notification Rule. The Security Rule final rule update is expected in May 2026 with materially stricter encryption, MFA, and audit-log controls.

REV.health relevance. The platform is architected against the Security Rule NPRM as if it were already final. Per-tenant KMS keys, mandatory MFA (FIDO2/WebAuthn preferred), per-resource access audit logs with 10-year retention by default, encryption in transit and at rest, BAAs with every sub-processor, and tabletop incident-response drills quarterly. See Technical Architecture for details.

12. No Surprises Act & Good Faith Estimates #

Description. The 2020 No Surprises Act bans balance billing for emergency services and certain out-of-network situations, and requires a Good Faith Estimate to self-pay patients before scheduled services.

REV.health relevance. The Scheduling module generates a GFE at booking for self-pay encounters using planned CPT(s) and a configurable fee schedule; the Eligibility module generates an insured cost estimate using parsed 271 benefits. Both estimates are surfaced to the patient and saved into the PMR with the encounter.

13. ADA / Section 508 / WCAG 2.2 AA #

Description. The Americans with Disabilities Act (1990, services), Section 508 (1998, federal IT), and WCAG 2.2 AA (the de facto digital accessibility target). Together they require keyboard navigation, screen-reader compatibility, color-contrast minima, and accessible forms across both the clinician UI and the patient portal.

REV.health relevance. Accessibility is a P0 product value. axe-core runs in CI on every component build; manual audits with assistive technology happen each release. A release with a P0 or P1 accessibility regression cannot ship.

14. SOC 2 Type II #

Description. An AICPA audit attestation across the Trust Services Criteria (Security, Availability, Processing Integrity, Confidentiality, Privacy). Type I attests to controls in design at a point in time; Type II attests to operating effectiveness over a period (typically 6–12 months).

REV.health relevance. SOC 2 Type I covers the P1 cohort; SOC 2 Type II is in place by launch. Drata or Vanta automates control evidence collection and continuous-monitoring posture, layered over an internal control narrative authored against the Trust Services Criteria.

15. HITRUST CSF #

Description. The Health Information Trust Alliance Common Security Framework. Three certification tiers: e1 (essentials), i1 (implemented, 1-year), r2 (risk-based, 2-year). Increasingly demanded by enterprise buyers and large health systems.

REV.health relevance. i1 in P2+ post-launch when the buyer pipeline justifies it; r2 evaluated in P3 as the platform expands beyond independent practices. HITRUST MyCSF is used as the assessor toolset; controls are mapped to HIPAA Security, NIST CSF, and SOC 2 to avoid duplicate evidence collection.

4. Integration Ecosystem #

Every external dependency carries a deliberate BUILD / BUY / HYBRID recommendation based on three questions: Is it a moat? Is the certification impossible to replicate? What does an outage cost the practice?

Decision Framework

• BUILD — first-class internal capability; integration is the wrapper, differentiation is the layer above.
• BUY — consume vendor as a black box; integrate via documented API/cert.
• HYBRID — vendor for transport or compliance, internal layer for differentiation or normalization.

5. IC Rules Reference #

REV.health is generated on top of the Infinite Cabinet (IC) platform, which has 14 non-negotiable hard rules governing code generation, schema evolution, deployment, and tenancy. Violating a rule is a system error, not a policy disagreement. Where REV.health takes a deliberate exception, the deviation is captured in the Architectural Decisions register.

Key Companion Conventions

• Entity naming: Singular PascalCase, no abbreviations. Patient not Patients; OrganizationID not OrgID.
• Audit fields (3 required on every entity): UpdatedDateTimeUTC, UpdatedByUserID, DeletedDateTimeUTC (nullable soft-delete). Org-scoped entities add OrganizationID as fourth.
• Money pattern: Two fields: {Concept}AmountMoney (Int, cents) + {Concept}CurrencyCodeString3 (ISO 4217). Avoids IEEE 754 precision loss.
• Short GUID: Case-sensitive Base62 encoding of 128-bit GUID v4 → ~22 chars. Deterministic, reversible, no lookup table. (DEC-RH-003)

6. Data Ownership Model #

In REV.health, PHI belongs to the patient. Clinical facts are global data that travel with the patient across practices, while billing and operational data is org-scoped. Every read of a chart is audited with a traceable authorization chain.

Patient = User Identity

• A patient IS a user. PatientID = UserID. Single identity, single login, single record.
• Patient registration is idempotent — existing patient gets linked to new practice via PatientOrgMembership, not a new record.
• A patient changing practices does not become a different person; their chart survives across orgs.

Global vs. Org-Scoped Classification

Key Linking Entities

• PatientOrgMembership — records patient registered at a practice. Org-scoped, carries OrganizationID.
• CareRelationship — long-term care team link (Patient ↔ Provider within an org). Org-scoped.
• Encounter — clinical visit. Org-scoped (belongs to the practice where it occurred), but encounter note content is globally visible with source attribution.

Billing: Sharable vs. Private

• Sharable: CPT codes, fee schedules, ICD-10-CM diagnosis codes linked to encounters (clinical facts).
• Private per org: Payments received, claim submissions (837P), denial details, ERA posting, write-offs, adjustments, collection actions.

Read-Access Audit Trail

Every read captures: Who (UserID), What (entity type + ID), When (ViewedDateTimeUTC), How (access channel), and Authorization Chain (why permitted).

Patients see "Who has viewed your records" as a first-class portal feature. Audit logs are hash-chained, write-once (S3 Object Lock), retained 25 years by default.

7. Contract Topology #

REV.health separates its service contract (Terms of Service) from its patient-data authorization framework (Terms of Care) across five documents binding three parties:

Why separate documents?

• The patient is not a party to the Platform ToS — they need their own data-rights documents.
• The practice has its own legal relationship with the patient (NPP, Patient ToS) — REV.health is the technology provider, not the contracting party.
• Authorization chains span organizations — the ToC provides the cross-org vocabulary.
• Regulatory requirements are distinct: HIPAA overall, 42 CFR Part 2 separate consent, Cures Act information-blocking prohibitions.

Key Consent Models

• Opt-out (default): Clinical data shareable within REV.health ecosystem and via TEFCA for TPO. Patients may opt out of TEFCA queries, cross-practice visibility, or research use of de-identified data.
• Explicit consent (granular): Required for SUD records (Part 2), psychotherapy notes, HIV status (state-specific), genetic info (GINA), reproductive health (state-specific).
• Break-the-glass (emergency): Clinician provides justification (≥50 chars), full chart access for 4 hours, mandatory 24-hour post-hoc review, patient notified within 48 hours.

Patient ToC — Your Data Rights #

The Patient ToC is the patient's data-rights and consent framework — a plain-language document accessible from the portal at any time (Settings → My Data Rights). It is presented on the practice-branded portal, but the data-rights commitments are enforced by the REV.health platform regardless of which practice the patient visits.

• See your whole record. You can view your complete clinical record at any time — problems, medications, allergies, labs, imaging, immunizations, notes, care plans. No gatekeeping, no 30-day waits.
• See who looked. Every time someone views your chart, it's logged. You can see the full list: who, when, and why. No hidden access.
• Get an electronic copy. You can download your data as a standard medical file (FHIR JSON or C-CDA) at no cost. Third-party apps you authorize can also read your data via the patient access API.
• Restrict sensitive data. You can restrict who sees substance-use records, psychotherapy notes, HIV status, genetic information, and reproductive health data. Each category requires your explicit consent before anyone can see it.
• Change your mind. You can revoke any consent grant at any time. Revocation takes effect immediately.
• Know about emergency access. If a clinician accesses your chart in an emergency without your prior consent, you'll be notified within 48 hours with their name, organization, and reason.
• Request corrections. You can request amendments to your record. The practice must respond in writing. Your original record is never overwritten — amendments are appended.

Patient ToC — Your Consent Dashboard #

The patient portal includes a Consent Dashboard that shows:

• Active consent grants — who you've authorized, what they can see, when it expires.
• Restricted categories — which sensitive-data categories are locked, who (if anyone) has been granted access.
• Read-access log — every chart view in the last 90 days (full history available on request).
• Emergency-access events — break-the-glass notifications and 24-hour review outcomes.
• Cross-practice sharing — which practices can see your global clinical data, and your opt-out controls.

Patient ToC — How Your Data Moves Between Practices #

• Global data is shared by default. Allergies, medications, problems, labs, and other clinical facts are visible to every practice where you're a patient, so your care team has the full picture. You can opt out of cross-practice sharing in your consent dashboard.
• Billing is never shared. What you owe Practice A is invisible to Practice B. Financial data stays within the practice that generated it.
• Referrals are scoped. When your doctor refers you to a specialist, the specialist sees only the information your doctor chose to share — not your whole chart. You can expand the scope with your consent.
• Sensitive records stay locked. Substance-use, mental health, and other restricted categories are never shared between practices without your explicit consent, even within the REV.health ecosystem.

Platform ToC — Authorization Chains #

Every access to patient data requires a valid, traceable authorization chain that establishes why the viewer is permitted to see the data. There are five canonical chain types.

Care Organization Member

A clinician or staff member at a practice where the patient has an active PatientOrgMembership is authorized by the practice's ToC acceptance (signed during onboarding), their employment/contracting relationship (verified via the practice's identity provider), and their RBAC level. The chain is: Org ToC Acceptance → Org Membership → RBAC Level → Data Category Access. If the organization's ToC acceptance has lapsed (annual renewal required), access is denied until renewal is completed.

Family Member / Proxy

A family member or legally authorized representative is authorized by an explicit consent grant from the patient (or, for minors, the parent/guardian with decision-making authority), the scope of that grant, and the relationship type. The chain is: Patient Consent Grant → Scope → Relationship Type → Data Category Access. Grants are revocable at any time, effective immediately. State-by-state minor consent rules (mature minor doctrine, emancipated minors) are enforced by the consent engine.

External Specialist (Referral)

An external specialist who receives a referral is authorized by the referral order (which includes the patient's consent to share), the receiving organization's ToC acceptance (or equivalent mutual BAA/ToC), and the specialist's role. The chain is: Referral Order + Patient Consent → Receiving Org ToC Acceptance → Specialist Role → Data Category Access (scoped to referral reason). Access is scoped to the referral reason; expanded access requires explicit patient consent.

TEFCA Requester

An authorized TEFCA requester is authorized by the QHIN-participant agreement, a permitted purpose under the Common Agreement (treatment, payment, health care operations, public health, research with IRB, individual access services), and the patient's right to request restrictions. The chain is: QHIN Agreement → Permitted Purpose → Patient Restrictions Check → Data Response (with redisclosure notice for Part 2).

Researcher / Public Health Authority

A researcher or public-health authority is authorized by IRB/privacy-board approval plus a Data Use Agreement (research) or the authority's legal mandate (public health), with de-identification or a limited data set. The chain is: IRB Approval / Public Health Mandate → De-identification or DUA → Data Response.

Platform ToC — Consent Models #

REV.health supports three consent models, each with explicit patient control.

Opt-Out (Default)

By default, clinical data is shareable within the REV.health ecosystem and via TEFCA for treatment, payment, and health care operations. Patients may opt out of TEFCA queries, cross-practice visibility within REV.health, and research use of de-identified data. Opt-out does not block access by the patient's own care team at their registered practice, nor legally mandated reporting (notifiable diseases, abuse, court orders).

Explicit Consent (Granular)

For sensitive data categories, explicit consent is required before any access:

• Substance use disorder records (42 CFR Part 2): Patient must consent to each disclosure, specifying recipient, purpose, and expiration.
• Psychotherapy notes: Separate consent required under HIPAA; never included in general chart views.
• HIV status (in states with heightened protection): state-specific consent enforced by the consent engine.
• Genetic information: GINA protections enforced; no disclosure to employers or insurers.
• Reproductive health: state-specific protections enforced post-Dobbs, varying by jurisdiction.

Each consent grant is recorded as a ConsentGrant entity with fields: ConsentGrantID (PK), PatientID (FK → Patient), RecipientTypeString, RecipientID, ScopeString, PurposeString, ExpirationDateTimeUTC, IsRevokedBool, plus the three audit fields (+ OrganizationID on org-scoped).

Break-the-Glass (Emergency Override)

In a genuine emergency where obtaining consent is not feasible, a clinician may invoke break-the-glass access — see below.

Platform ToC — Break-the-Glass Emergency Access #

Break-the-glass is a controlled override that permits access in emergencies while ensuring post-hoc accountability:

• Invocation: The clinician selects "Emergency Access" and provides a free-text justification (minimum 50 characters describing the emergency). No pre-approval is required — the emergency is the authorization.
• Scope: Grants full chart access, including data that would otherwise require explicit consent (Part 2, psychotherapy notes). This is deliberate: in a life-threatening emergency the clinician needs all available information.
• Time limit: Access expires after 4 hours. Continued access requires normal authorization (care org membership, consent grant, or referral).
• Mandatory review: Within 24 hours, the patient's primary care physician (or the practice's privacy officer) reviews the access. If the justification is inadequate, the event is flagged for compliance investigation.
• Patient notification: The patient is notified via the portal within 48 hours, including the clinician's name, org, and justification.
• Audit logging: Logged with ActionTypeString = "BreakTheGlass", the full justification, and a link to the 24-hour review record. Included in the patient's "Who has viewed your records" panel.

Break-the-glass is governed by the Terms of Care, not the ToS, because it concerns the authorization chain, not the service contract. The practice accepts these provisions when it signs the ToC during onboarding.

Platform ToC — Audit Trail Commitments #

• Every read is logged. No exceptions. The system does not distinguish "significant" from "insignificant" reads — every access creates an audit entry. See Data Ownership Model for the full data model.
• Authorization chain is always recorded. Every entry includes AuthorizationChainTypeString and AuthorizationChainDetailString. There is no audit entry without an authorization chain.
• Patient visibility. Patients see their complete read-access audit trail in the portal. If someone viewed the chart, the patient knows about it.
• Tamper evidence. Audit logs are hash-chained and written to write-once S3 storage. Altering a past entry invalidates the chain; automated daily integrity checks verify it.
• 10-year minimum retention. Logs are retained for the longer of 25 years (REV.health default) or the state-mandated period. Never soft-deleted.
• Compliance reporting. Practices can generate compliance reports (HIPAA accounting of disclosures, Part 2 redisclosure tracking, access-by-role summaries) on demand.

Platform ToC — Cross-Org Data Sharing Rules #

When two REV.health practices treat the same patient, the following rules govern cross-org sharing:

• Global data is shared by default. Clinical facts (allergies, medications, conditions, vitals, labs, imaging, immunizations, care plans) are visible to all practices where the patient has an active membership, unless the patient has opted out of cross-practice visibility.
• Org-scoped data is never shared. Billing, claims, denials, appointments, internal tasks, and financial records are siloed per org. Practice A cannot see Practice B's claim submissions or patient payment records.
• Encounter notes are shared with attribution. An encounter note created at Practice A is visible to Practice B with clear attribution: "Encounter at [Practice A] on [date] by [Dr. M]." Note content is global; billing for that encounter is org-scoped.
• Source OrganizationID is always displayed. When a clinician at Practice B views an allergy added at Practice A, the UI shows "Added at [Practice A] by [Dr. M] on [date]." The source is displayed, not hidden.
• Referrals carry scoped data bundles. A referral includes the data scope defined by the referring clinician (default: full chart; configurable), delivered as a USCDI bundle (FHIR ServiceRequest + Patient + Practitioner + Organization + supporting clinical resources). Practice B can only access the referral-scoped data unless the patient grants expanded consent.
• Part 2 records require separate consent per org. Even within the REV.health ecosystem, SUD records require explicit patient consent before they are visible to a second practice. The opt-out default does not apply to Part 2 data.

Platform ToC — Acceptance and Renewal #

Every organization using REV.health must accept the Terms of Care during onboarding. The acceptance is recorded with the organization's OrganizationID, the signatory's UserID (typically the practice manager or privacy officer), the acceptance DateTimeUTC, and the version of the ToC accepted (SemVer break.feature.bug).

Annual renewal is required. If an organization's ToC acceptance lapses, all staff at that organization lose access to patient data (they see a "Terms of Care renewal required" message). Renewal ensures staff acknowledge any changes to the authorization-chain model, break-the-glass provisions, or audit commitments since the last acceptance.

8. Architectural Decisions #

Catalog of deliberate deviations from IC hard rules and new conventions introduced by REV.health. When a future developer asks "why is there no OrganizationID on the User table?", the answer is here.

9. Known Contradictions #

Source documents disagree. These are intentional tensions — cases where two legitimate requirements point in opposite directions. REV.health prefers transparency over false consistency.

10. icApplication Reference #

The canonical reference for the IC generation flow that applies identically to all 10 modules. Each module's icApplication page links here for the 80% shared content and only documents module-specific overrides.

Shared Technology Stack

Project Directory Skeleton

Seven of ten modules follow this standard skeleton. Three outliers (Scheduling, Clinical Documentation, Coding/CDS) have their own layouts on their icApplication pages.

modules/{noun}/
├── ami/                    # HAND-AUTHORED — one AMI file per entity
├── rules/                  # HAND-AUTHORED — override bindings, validation rules
├── api/                    # GENERATED (DB → API stage)
├── components/             # GENERATED (API → Components stage)
├── adapters/               # HAND-WRITTEN (vendor SDK glue)
├── jobs/                   # HAND-WRITTEN (async workers)
├── deploy/                 # DI manifests: dev/qa/uat/prod
└── README.md

Only ami/ and rules/ are hand-authored. Everything in api/ and components/ is regenerated on each ic generate run. Generation order: DB → API → Components → Deploy (IC Rule #1).

Code Generation Flow

1. DB stage: Cosmos container definitions materialized from AMI. Org-scoped containers get OrganizationID partition key + audit triplet + standard indexes. Global containers use global audit pattern (SourceOrganizationID in trail).
2. API stage: REST and GraphQL endpoints generated from AMI + rules. FK validation lives here (Rule #14). Service tokens scope every query by OrganizationID.
3. Components stage: Angular components generated from API contract + binding tables. Tag pattern: ic-ng21-{noun}-{break}-{name}. Shipped to IC CDN at fully versioned URL.
4. Deploy stage: DI manifest binds each consumer to specific component + API version (Rule #2). Deployments cascade left-to-right (Rule #6).

Default AMI → Component Bindings

Environment Cascade