Data classification

Global entities that are not clinical facts — Provider, Practice, Pharmacy, Specialty — also use the SourceOrganizationID audit pattern rather than OrganizationID. They are reference data shared across the platform; their identity is not partitioned by tenant.

FK relationship diagram

flowchart LR
  subgraph Global["Global entities"]
    Patient((Patient))
    Provider((Provider))
    Practice((Practice))
    Pharmacy((Pharmacy))
    Specialty((Specialty))
    User((User))
  end

  subgraph Clinical["Clinical facts (global + SourceOrganizationID)"]
    Allergy[Allergy]
    Medication[Medication]
    Condition[Condition]
    Vital[Vital]
    LabResult[LabResult]
    Imaging[Imaging]
    Immunization[Immunization]
    Surgery[Surgery]
    FamilyHistory[FamilyHistory]
    CarePlan[CarePlan]
    Screening[Screening]
    Order[Order]
    Document[Document]
    Referral[Referral]
    Message[Message]
    Encounter[Encounter]
  end

  subgraph Provenance["Provenance / Interop (org-scoped)"]
    ExternalInbound[ExternalInbound]
    ExternalOutbound[ExternalOutbound]
    ExternalSourceSystem[ExternalSourceSystem]
    ExternalRecipient[ExternalRecipient]
  end

  subgraph Operational["Operational (org-scoped)"]
    Reminder[Reminder]
    RuleVersion[RuleVersion]
    AuditLog[AuditLog]
  end

  Patient --> Allergy
  Patient --> Medication
  Patient --> Condition
  Patient --> Vital
  Patient --> LabResult
  Patient --> Imaging
  Patient --> Immunization
  Patient --> Surgery
  Patient --> FamilyHistory
  Patient --> CarePlan
  Patient --> Screening
  Patient --> Order
  Patient --> Document
  Patient --> Referral
  Patient --> Message
  Patient --> Encounter
  Patient --> ExternalInbound
  Patient --> ExternalOutbound
  Patient --> Reminder

  Provider --> Medication
  Provider --> Surgery
  Provider --> Encounter
  Provider --> Order
  Provider --> Referral
  Provider --> Practice

  Practice --> User

  Pharmacy --> Patient

  Encounter --> Vital
  Encounter --> Document

  Order --> LabResult
  Order --> Imaging

  ExternalSourceSystem --> ExternalInbound
  ExternalRecipient --> ExternalOutbound

  ExternalInbound --> Allergy
  ExternalInbound --> Medication
  ExternalInbound --> Condition
  ExternalInbound --> Surgery
  ExternalInbound --> LabResult
  ExternalInbound --> Imaging
  ExternalInbound --> Immunization
  ExternalInbound --> Document

  RuleVersion --> Screening
  RuleVersion --> Reminder

  User --> AuditLog
  User --> Message
  User --> Vital
  User --> Immunization
  User --> Document
        

Solid arrows = FK direction (child → parent reads as “child references parent”). Per IC hard rule #14, FKs are enforced by the generated API layer, not by database FK constraints. Clinical-fact entities cross the org boundary by referencing global Patient and Provider without OrganizationID partitioning — they carry SourceOrganizationID in their audit trail instead.

Patient P0

One row per patient. GLOBAL — no OrganizationID. Patient identity is not partitioned by tenant; the patient owns their own record. Uses the SourceOrganizationID pattern to record which org contributed the row.

Trust tier: 2 (clinician-attested in-system for demographics; inbound imports may be tier 0–1).

RBAC: Read ≥ 1, Write demographics ≥ 51, EditAMI ≥ 90.

Provider P0

One row per clinician or prescriber. GLOBAL — no OrganizationID. Provider identity spans practices; a provider may practice at multiple orgs.

Trust tier: 2 (clinician-attested in-system; NPI verified against NPPES).

RBAC: Read ≥ 1, Write ≥ 70 (practice manager), EditAMI ≥ 90.

Practice P0

One row per practice organization. GLOBAL — no OrganizationID. A practice is a reference entity shared across the platform; the PracticeID is the OrganizationID value used in org-scoped tables.

Trust tier: 2 (internal canonical; Tax ID and NPI verified).

RBAC: Read ≥ 1, Write ≥ 70 (practice manager), EditAMI ≥ 90.

Pharmacy P0

One row per pharmacy. GLOBAL — no OrganizationID. Pharmacy is a reference entity; patients and prescriptions reference it across all orgs.

Trust tier: 3 (verified by NCPDP directory — authoritative).

RBAC: Read ≥ 1, Write ≥ 70 (practice manager), EditAMI ≥ 90.

Specialty P0

One row per medical specialty. GLOBAL — no OrganizationID. Reference lookup for provider specialty codes.

Trust tier: 3 (verified by NPI taxonomy — authoritative).

RBAC: Read ≥ 1, Write ≥ 90 (EditAMI only).

Encounter P0

One row per clinical encounter (visit). Org-scoped. Encounters are operational events owned by the practice where they occurred.

Trust tier: 2 (clinician-attested in-system — confirmed).

RBAC: Read ≥ 1, Write intake ≥ 51 (front desk, MA), Write clinical ≥ 51 (nurse, physician), EditAMI ≥ 90.

Allergy P0

One row per patient allergy or intolerance. GLOBAL — clinical fact with SourceOrganizationID audit. A deliberate exception to IC hard rule #11: allergies belong to the patient and are visible across all orgs, with SourceOrganizationID recording which org contributed the data.

Trust tier: 1 (patient-attested) – 3 (verified by source-of-truth such as pharmacy fill or allergist report).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Medication P0

One row per active or historical medication on the patient’s med list. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11; the patient owns their medication history across all prescribing orgs.

Trust tier: 1 (patient-attested) – 3 (verified by pharmacy fill or prescriber).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Condition P0

One row per problem, diagnosis, or health concern on the patient’s problem list. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11.

Trust tier: 1 (patient-attested) – 3 (verified by source-of-truth).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Surgery P0

One row per surgical procedure in the patient’s history. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11.

Trust tier: 1 (patient-attested) – 3 (verified by surgical report).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

FamilyHistory P1

One row per family-member condition on the patient’s family history. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11.

Trust tier: 1 (patient-attested — working knowledge; clinician confirmation required for high-stakes fields).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Vital P0

One row per vital-sign measurement. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11. Home-entered and clinic-entered vitals share the same noun, distinguished by RecordedByUserID + trust tier.

Trust tier: 1 (patient home entry) – 2 (clinician-recorded in encounter).

RBAC: Read ≥ 1, Write ≥ 51 (MA, nurse), EditAMI ≥ 90.

LabResult P0

One row per lab test result. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11. Lab results are patient-owned; the performing lab may be external.

Trust tier: 3 (verified by source-of-truth — lab feed is authoritative).

RBAC: Read ≥ 1, Write ≥ 51 (lab tech, clinician), EditAMI ≥ 90.

Imaging P0

One row per imaging study. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11.

Trust tier: 3 (verified by source-of-truth — signed radiology report is authoritative).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Order P0

One row per clinical order (lab, imaging, referral). Org-scoped. Orders are operational events initiated by a practice.

Trust tier: 2 (clinician-attested in-system — confirmed).

RBAC: Read ≥ 1, Write ≥ 51 (clinician, lab tech for status), EditAMI ≥ 90.

Immunization P0

One row per immunization administered or recorded. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11.

Trust tier: 1 (patient-attested) – 3 (verified by immunization registry).

RBAC: Read ≥ 1, Write ≥ 51 (MA, nurse), EditAMI ≥ 90.

CarePlan P0

One row per care plan (a named, categorized set of tasks for a patient). GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11. The care plan is the living, computable per-patient plan that updates itself as conditions change.

Trust tier: 2 (clinician-attested in-system; rules auto-generate, clinicians confirm or override).

RBAC: Read ≥ 1, Write ≥ 51 (nurse, physician), EditAMI ≥ 90.

Screening P1

One row per screening or preventive service due/completed for a patient. GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11. Each screening pins a RuleVersionID for determinism.

Trust tier: 2 (rule-generated, clinician-confirmed).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Reminder P0

One row per concrete reminder to send. Org-scoped. Reminders are operational — they are persisted as absolute UTC datetimes and polled by the dispatcher. T-offsets are configuration only; the DB stores the computed send time, not the offset formula. See Section 6 for the full worked example.

Trust tier: 2 (clinician-attested in-system — confirmed).

RBAC: Read ≥ 1, Write ≥ 51 (nurse, care coordinator), ManageFeatures ≥ 80, EditAMI ≥ 90.

Document P0

One row per clinical document (note, letter, report). GLOBAL — clinical fact with SourceOrganizationID audit. Deliberate exception to IC hard rule #11.

Trust tier: 2 (clinician-authored in-system) – 3 (verified by signed external report).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Referral P0

One row per referral. Org-scoped. Cross-references the Referrals module. Referrals are operational events initiated by a practice to send a patient to a specialist.

Trust tier: 2 (clinician-attested in-system — confirmed).

RBAC: Read ≥ 1, Write ≥ 51 (clinician), EditAMI ≥ 90.

Message P1

One row per internal message between users about a patient. Org-scoped. Messages are operational communications owned by the practice.

Trust tier: 2 (internal canonical — authored by credentialed users in-system).

RBAC: Read own ≥ 1, Write ≥ 51, EditAMI ≥ 90.

ExternalInbound P0

One row per external payload received (HL7v2, FHIR, CCDA, X12, fax+OCR, partner JSON). Org-scoped. Immutable once created — the canonical receipt for provenance and dispute resolution.

Trust tier: 0 (unverified inbound) until mapping and review promote child clinical-fact rows to tier 1–3.

RBAC: Read ≥ 51 (clinician, integration admin), Write system-only (service principal), EditAMI ≥ 90.

ExternalOutbound P0

One row per outbound payload sent to an external recipient. Org-scoped. Immutable once created — the canonical receipt for what was sent and when, including any redactions applied.

Trust tier: 2 (rendered from clinician-attested data in-system).

RBAC: Read ≥ 51 (clinician, integration admin), Write system-only (service principal), EditAMI ≥ 90.

ExternalSourceSystem P0

One row per external source system that sends data to rev.health. Org-scoped. Configuration entity for inbound interop.

Trust tier: N/A (configuration, not clinical data).

RBAC: Read ≥ 70 (integration admin), Write ≥ 70, EditAMI ≥ 90.

ExternalRecipient P0

One row per external recipient that receives data from rev.health. Org-scoped. Configuration entity for outbound interop.

Trust tier: N/A (configuration, not clinical data).

RBAC: Read ≥ 70 (integration admin), Write ≥ 70, EditAMI ≥ 90.

RuleVersion P0

One row per versioned clinical rule. Org-scoped. Every CarePlanTask and Screening pins a RuleVersionID so the care plan is reproducible from inputs + rule version. Rules are their own noun-app, not inline logic.

Trust tier: N/A (configuration, not clinical data).

RBAC: Read ≥ 51, Write ≥ 80 (practice admin), EditAMI ≥ 90.

User P0

One row per system user (clinician, staff, admin). GLOBAL — no OrganizationID. User identity is global; a person may work across multiple practices. Uses the SourceOrganizationID audit pattern.

Trust tier: 2 (internal canonical; identity proofed via SSO + MFA).

RBAC: Read ≥ 1 (own profile), Write ≥ 70 (practice manager), Admin ≥ 100, EditAMI ≥ 90.

AuditLog P0

One row per auditable action (read or write) across all noun apps. Org-scoped. Immutable — the system appends only; no updates or deletes. Captures the authorization-chain trace for every data touch.

Trust tier: N/A (audit infrastructure, not clinical data).

RBAC: Read ≥ 70 (practice admin, compliance), Write system-only, EditAMI ≥ 90.

Provenance model

The canonical record is the set of noun-app rows themselves. There is no separate canonical document. Provenance is captured by FK and trust tier on each row. Three forms of every clinical fact exist:

(a) Internal canonical provenance

Records created within rev.health by credentialed users. These rows have SourceInboundID = null (or the literal string “manual” in a metadata field) and a TrustTier of 1–2 depending on the attesting role. Editable per RBAC permission rules with full audit.

(b) External inbound provenance

Records received from external systems via ExternalInbound. One row per external payload (HL7v2, FHIR R4, CCDA, X12, fax+OCR, partner JSON). The inbound row stores the raw payload + source + format + timestamp + mapping version applied. Immutable once created. Applied clinical-fact rows carry SourceInboundID FK back to the originating payload for full traceability.

(c) External outbound provenance

Records sent to external systems via ExternalOutbound. One row per send. Stores the rendered payload + recipient + format + timestamp + hash + redactions applied. Immutable. We have exactly what we sent and when.

(d) Trust tier definitions

(e) Conflict handling rules

• Both rows preserved. When patient says X and a pharmacy fill says Y, both rows remain in the patient’s record. We never destroy the prior value.
• Reconciliation card lands in coordinator queue. A reconciliation card is created and placed in the care coordinator’s queue. The dashboard alert lane surfaces the conflict until a clinician resolves it.
• Superseded rows are marked with reason. When a clinician resolves a conflict by choosing one value over another, the superseded row is marked with a reason code — it is not soft-deleted. DeletedDateTimeUTC stays null; the row remains visible for audit.
• Patient corrections never silently overwrite clinician-attested data. A patient “❌ this is wrong” on a clinician-attested or hospital-attested fact goes to reconciliation, not to direct edit.

RBAC matrix (IC 0–100 scale)

Permission checks happen client-side AND API-side every time, against the 0–100 scale, scoped per app per env per group. MFA required for any role at level ≥ 51. Field-level encryption on PHI columns. Every read and write creates an AuditLog row.

Worked Reminder example (VAL-CONTENT-042)

A full end-to-end worked example of the Reminder lifecycle, from creation through dispatch, attempt, and supersession.

(a) Reminder AMI schema

See the Reminder entity above (entity #19) for the full AMI schema. Every reminder is persisted as a concrete UTC datetime row that the dispatcher polls against.

(b) ReminderAttempt AMI schema

One row per delivery attempt for a reminder. Records each attempt with outcome for retry visibility and dead-letter tracking.

(c) Offset ladder

For each CarePlanTask, the system generates a ladder of concrete Reminder rows at these offsets from the task’s DueDateTimeUTC:

Computation: ScheduledSendDateTimeUTC = DueDateTimeUTC + offset, normalized to patient’s preferred contact window (9am–8pm patient-local), then converted back to UTC for storage. Computed once at write time and persisted. Never re-derived implicitly.

(d) Dispatcher SQL query

SELECT * FROM Reminder
WHERE OrganizationID = @practice
  AND IsSentBool = false
  AND DeletedDateTimeUTC IS NULL
  AND StatusCode = 'scheduled'
  AND ScheduledSendDateTimeUTC <= @nowUtc
ORDER BY ScheduledSendDateTimeUTC ASC

The dispatcher runs this query on a poll interval. It is the only thing it does. No business logic lives in the dispatcher beyond dequeue + hand-off to the channel provider.

(e) Frequency cap

Max 3 attempts per patient per day across all channels. Applied at dispatcher dequeue, not at schedule time, so the underlying schedule stays intact. If a patient already has 3 attempts today, the dispatcher skips that row until the next day.

(f) Supersession logic

If CarePlanTask.DueDateTimeUTC changes (e.g., physician overrides the due date), the system:

1. Marks prior Reminder rows for that task with StatusCode = “superseded”.
2. Keeps superseded rows for audit — DeletedDateTimeUTC stays null.
3. Generates a fresh ladder of Reminder rows based on the new DueDateTimeUTC.

This ensures the reminder history is always traceable, and no prior value is destroyed.

(g) Reminder lifecycle diagram

flowchart TD
  A[CarePlanTask created or updated] --> B[Generate offset ladder]
  B --> C[Create Reminder rows with ScheduledSendDateTimeUTC]
  C --> D[Dispatcher polls: ScheduledSendDateTimeUTC <= nowUtc?]
  D -- Yes --> E{Frequency cap OK?}
  E -- Yes --> F[Dequeue + dispatch via channel]
  E -- No --> G[Skip until next day]
  D -- No --> D
  F --> H[Create ReminderAttempt row]
  H --> I{IsSuccessBool?}
  I -- Yes --> J[Reminder.StatusCode = sent / delivered]
  I -- No --> K[ReminderAttempt.ErrorMessageString recorded]
  K --> L{Retry count < max?}
  L -- Yes --> D
  L -- No --> M[Dead-letter: StatusCode = failed]
  J --> N{Patient responded?}
  N -- Yes --> O[Reminder.ResponseCodeString = confirmed / declined / rescheduled]
  N -- No --> P[Next ladder rung fires]
  A2[DueDateTimeUTC changed] --> Q[Mark prior Reminders StatusCode = superseded]
  Q --> B
  O --> R[Reminder lifecycle complete]
        

Worked Allergy versioning example (VAL-CONTENT-043)

A worked example demonstrating AMI schema versioning on the Allergy entity, covering a backward-compatible feature bump (1.1.0) and an illustrative breaking change (2.0.0).

(a) Allergy 1.0.0 — initial creation

The initial schema as documented in the Allergy entity above (entity #7). This is the “before” schema. Key fields include AllergyID, PatientID, AllergenCodeString50, AllergenNameString100, AllergenTypeString50, ReactionString200, SeverityString50, VerificationStatusString50, plus the three audit fields with SourceOrganizationID pattern.

Note: OnsetDateString50 is not present in v1.0.0. The field was added in v1.1.0.

(b) Allergy 1.1.0 — feature bump (backward-compatible)

Add an optional field OnsetDateString50 to capture the approximate onset date or year of the allergy. This is a backward-compatible addition: existing rows continue to work with OnsetDateString = null.

(c) Allergy 2.0.0 — break bump (illustrative)

Make OnsetDateString50 required and change its type from String to DateTime. This is a breaking change: existing rows with null or free-text onset values cannot satisfy the new contract.

This illustrates the IC versioning contract: feature bumps (minor) are additive and backward-compatible; break bumps (major) require a new database, ETL migration, a grace period, and explicit EditAMI authorization.