5 domain clusters + 15 cross-cluster reasoning chains. User-centered — every entity exists in relation to one specific person's situation.
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 1 | User | HAS | Insurance Plan |
| 2 | User | EARNS | Income Bracket |
| 3 | User | LIVES_IN | Location |
| 4 | User | HAS_CONDITION | Health Status |
| 5 | User | CAN_AFFORD | Monthly Premium |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 6 | Insurance Plan | HAS_TYPE | HMO |
| 7 | Insurance Plan | HAS_TYPE | PPO |
| 8 | Insurance Plan | HAS_TYPE | HDHP |
| 9 | Insurance Plan | HAS_COST | Monthly Premium |
| 10 | Insurance Plan | HAS_COST | Deductible |
| 11 | Insurance Plan | HAS_COST | Copay |
| 12 | Insurance Plan | HAS_COST | Coinsurance |
| 13 | Insurance Plan | HAS_LIMIT | Out-of-Pocket Maximum |
| 14 | Insurance Plan | INCLUDES | In-Network Providers |
| 15 | Insurance Plan | EXCLUDES | Out-of-Network Providers |
| 16 | Insurance Plan | REQUIRES | Primary Care Physician |
| 17 | Insurance Plan | COVERS | Preventative Care |
| 18 | Insurance Plan | COVERS | Mental Health |
| 19 | Insurance Plan | COVERS | Prescriptions |
| 20 | Insurance Plan | COVERS | Emergency Care |
| 21 | Employer | CONTRIBUTES_TO | Monthly Premium |
| 22 | Employer | SETS | Enrollment Window |
| 23 | Employer | DEFINES | Waiting Period |
| 24 | HDHP | PAIRS_WITH | HSA Account |
| 25 | User | SELECTS | Insurance Plan |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 26 | Care System | HAS_PROVIDER | Primary Care Physician |
| 27 | Care System | HAS_PROVIDER | Specialist |
| 28 | Care System | HAS_PROVIDER | Urgent Care |
| 29 | Care System | HAS_PROVIDER | Emergency Room |
| 30 | Care System | HAS_PROVIDER | Telehealth |
| 31 | Primary Care Physician | SERVES_AS | First Point of Contact |
| 32 | Specialist | REQUIRES | Referral (HMO) |
| 33 | Urgent Care | COSTS_LESS_THAN | Emergency Room |
| 34 | Telehealth | IS_COVERED_BY | Most Modern Plans |
| 35 | Visit Type | HAS_CATEGORY | Preventative |
| 36 | Visit Type | HAS_CATEGORY | Acute |
| 37 | Preventative Visit | IS_FREE_UNDER | ACA Guidelines |
| 38 | Acute Visit | TRIGGERS | Copay |
| 39 | Emergency Room Visit | TRIGGERS | Deductible |
| 40 | Provider | HAS_STATUS | In-Network |
| 41 | Provider | HAS_STATUS | Out-of-Network |
| 42 | In-Network Provider | COSTS_LESS_THAN | Out-of-Network Provider |
| 43 | HMO Plan | REQUIRES | Referral for Specialist |
| 44 | PPO Plan | ALLOWS | Direct Specialist Access |
| 45 | User | SHOULD_VERIFY | Network Status Before Visit |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 46 | Health Event | HAS_TYPE | Preventative |
| 47 | Health Event | HAS_TYPE | Acute |
| 48 | Health Event | HAS_TYPE | Chronic |
| 49 | Preventative Event | PREVENTS | Acute Crisis |
| 50 | Annual Physical | IS_COVERED_AT | Zero Cost (ACA) |
| 51 | Blood Panel | DETECTS | Early Risk Indicators |
| 52 | Early Risk Indicator | TRIGGERS | Preventative Action |
| 53 | Preventative Action | COSTS_LESS_THAN | Crisis Treatment |
| 54 | Acute Event | TRIGGERS | Unplanned Spending |
| 55 | Mental Health Episode | IS_COVERED_BY | Modern Insurance Plans |
| 56 | Chronic Condition | REQUIRES | Ongoing Care Plan |
| 57 | Chronic Condition | INCREASES | Annual Healthcare Cost |
| 58 | Life Stage Trigger | REQUIRES | Insurance Re-evaluation |
| 59 | New Job | IS_A | Life Stage Trigger |
| 60 | Aging Out of Parent Plan | IS_A | Life Stage Trigger |
| 61 | Moving to New City | AFFECTS | Provider Network Access |
| 62 | EOB Received | REQUIRES | Plain Language Translation |
| 63 | Lab Result | REQUIRES | Contextual Explanation |
| 64 | Enrollment Window | HAS_DURATION | 2–3 Weeks |
| 65 | User | EXPERIENCES | Life Stage Trigger |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 66 | Financial Document | HAS_TYPE | EOB |
| 67 | Financial Document | HAS_TYPE | Medical Bill |
| 68 | EOB | IS_NOT | Medical Bill |
| 69 | EOB | SHOWS | What Insurance Paid |
| 70 | Medical Bill | SHOWS | Patient Responsibility |
| 71 | Itemized Bill | CONTAINS | CPT Codes |
| 72 | CPT Code | REQUIRES | Plain Language Translation |
| 73 | Surprise Bill | VIOLATES | No Surprises Act (2022) |
| 74 | Patient Responsibility | EQUALS | Bill Minus Insurance Payment |
| 75 | User | HAS_RIGHT | Request Itemized Bill |
| 76 | Hospital | OFFERS | Financial Assistance Program |
| 77 | Financial Assistance | IS_UNKNOWN_TO | Most Patients |
| 78 | HSA | REQUIRES | HDHP Enrollment |
| 79 | HSA | PROVIDES | Triple Tax Advantage |
| 80 | FSA | HAS_RULE | Use It or Lose It |
| 81 | Medical Debt | CAN_AFFECT | Credit Score |
| 82 | Payment Plan | IS_AVAILABLE_AT | Most Hospitals |
| 83 | Payment Plan | IS_UNKNOWN_TO | Most Patients |
| 84 | User | SHOULD_NEGOTIATE | Medical Bill |
| 85 | Clarity | TRANSLATES | Financial Document → Plain Language |
| # | Entity A | Relationship | Entity B |
|---|---|---|---|
| 86 | User (healthy, low income) | SHOULD_SELECT | HDHP + HSA |
| 87 | User (chronic condition) | SHOULD_SELECT | PPO |
| 88 | User (new city) | MUST_REVERIFY | In-Network Providers |
| 89 | Life Stage Trigger | INITIATES | Full Plan Re-evaluation |
| 90 | Preventative Visit | REDUCES | Long-Term Financial Risk |
| 91 | Unmet Deductible | AFFECTS | Cost of Acute Visit |
| 92 | HSA Balance | OFFSETS | Out-of-Pocket Cost |
| 93 | Out-of-Network Visit | GENERATES | Surprise Bill Risk |
| 94 | Surprise Bill | TRIGGERS | No Surprises Act Protection |
| 95 | Mental Health Visit | IS_COVERED_EQUALLY | Physical Health Visit |
| 96 | Annual Physical | PREVENTS | Undetected Chronic Condition |
| 97 | Undetected Chronic Condition | INCREASES | Medical Debt Risk |
| 98 | Employer | FUNDS | Clarity Access |
| 99 | Clarity | BUILDS | User Health Literacy Over Time |
| 100 | Health Literate User | COSTS_LESS_THAN | Uninformed User (to employer) |
Each key entity in Clarity's KG maps to an authoritative real-world standard — proving the graph is verifiable, interoperable, and trustworthy.
| Clarity Entity | Standard / Ontology | Authority | Notes |
|---|---|---|---|
| Insurance Plan (HMO/PPO/HDHP) | HL7 FHIR InsurancePlan Resource | HL7 International | FHIR R4 defines plan types used in all US payer APIs |
| Deductible / Copay / OOP Max | ACA §1302 Cost-Sharing Rules | HHS / CMS | 45 CFR §156.130 — federally mandated disclosure fields |
| Primary Care Physician | FHIR Practitioner Resource + NPI Registry | HL7 / CMS | NPI = unique provider identifier; searchable via CMS API |
| Specialist | NUCC Health Care Provider Taxonomy | NUCC / CMS | 237 specialty codes; maps to NPI registry |
| Emergency Room | SNOMED CT: 225728007 | SNOMED International | "Accident and emergency department" clinical concept |
| Telehealth | CPT Modifier 95 / GT | AMA CPT | Telehealth billing modifiers; CMS coverage rules apply |
| Annual Physical / Preventative Visit | CPT 99381–99397 | AMA CPT Code Set | ACA mandates zero cost-sharing for these specific codes |
| Blood Panel / Lab Result | LOINC Codes | Regenstrief Institute | Universal standard for lab tests and clinical observations |
| Chronic Condition | ICD-10-CM Diagnosis Codes | WHO / CDC | 70,000+ diagnosis codes; mandatory for all US billing |
| Mental Health Visit | CPT 90832–90838 + Mental Health Parity Act | AMA / DOL | Parity Act (2008) mandates equal coverage with physical health |
| CPT Code | AMA CPT Code Set | American Medical Association | ~10,000 procedure codes; annual updates |
| EOB | FHIR ExplanationOfBenefit Resource | HL7 / CMS | CMS Blue Button 2.0 uses FHIR EOB for all Medicare data |
| HSA | IRS Publication 969 | Internal Revenue Service | Federal tax code defines eligibility, contribution limits, rules |
| No Surprises Act | 42 CFR Parts 749, 800, 826 | US Federal Law (CMS) | Effective Jan 1 2022; prohibits balance billing out-of-network |
| Enrollment Window | 45 CFR Part 155 | HHS / CMS | Federal regulation defines Special and Open Enrollment Periods |
Where will Clarity's AI fail — and what is the architecture to catch it? Eight failure modes mapped with severity and mitigation design.
| # | Failure Mode | Severity | Mitigation |
|---|---|---|---|
| 1 | Plan recommendation error — AI suggests HDHP to user with undiagnosed chronic condition | Critical | Complete health intake required before any plan recommendation; incomplete profiles flagged |
| 2 | Network status hallucination — AI states provider is in-network using stale data; user gets surprise bill | Critical | Live FHIR network API only; network status never cached >24hrs |
| 3 | EOB misread — AI tells user they owe money when EOB is informational only | Critical | Triple 68 (EOB IS_NOT Medical Bill) hardcoded as non-negotiable rule; never generated |
| 4 | State regulation blind spot — AI applies federal rules in state with different requirements | High | User.location (Triple 3) gates all regulatory guidance; state rule layer required at launch |
| 5 | CPT code hallucination — AI invents or misdescribes a procedure code | High | CPT descriptions from AMA database only; no generative description of medical codes |
| 6 | Mental health stigma — AI frames mental health coverage in ways that discourage use | High | Parity framing locked in prompt layer; human review on all mental health responses |
| 7 | Deductible math error — AI calculates remaining deductible incorrectly from stale claims data | High | Deductible tracker requires live EOB feed; uncertainty shown when data >7 days old |
| 8 | Financial assistance invisibility — AI fails to surface charity care programs the user qualifies for | Medium | Triple 77 hardcoded as proactive trigger; always surface assistance before payment options |
| # | Open Question | Risk | Mitigation Path |
|---|---|---|---|
| 1 | Will employees trust an employer-funded health app with their personal data? | High | Structural privacy firewall; independent data store; explicit user consent flow |
| 2 | Does plan recommendation trigger insurance advisor licensing requirements? | High | Legal review pre-launch; "guidance not advice" framing; human consultant as licensed layer |
| 3 | Can Clarity access real-time FHIR data from employer insurance carriers? | Med | API partnerships with carriers; CMS interoperability rules help but vary by carrier |
| 4 | How do we handle 50-state insurance regulation variation at scale? | Med | Location entity gates all regulatory guidance; state-specific layer is a significant build |
| 5 | What happens when Clarity's recommendation conflicts with employer's preferred plan? | Med | Fiduciary-like duty to user written into employer contract language explicitly |