Commonwealth Medallion Model

PART 1Grains

Every grain is built on Athena's claim table and its originalclaimid family link. The three core grains are the encounter, the claim and the service line. Every other grain is one of those plus a COB position.

Encounter

The silver docs define it as "a single billable event scoped to who is billing": a surgery produces separate encounters for the surgeon, the anesthesiologist and the facility. Athena has no such object, so the claim family stands in for it.

How a family is formed (models/silver/staging/stg_claim_family.sql):

• root_claim_id = coalesce(nullif(originalclaimid, ''), claimid). A claim with no original is its own root.
• encounter_id = sk(root_claim_id), which is md5('athena:' || context_id || ':' || root).
• The family is built over raw bronze_claim, not over submissions. The docs count 119,433 claims never billed at any position, and they are still encounters.

Patient, department, provider, TIN, diagnosis, admit dates and primary coverage all come from the attribute claim. encounter_coverage selects on the same flag, so the encounter and its coverage can't describe different claims. Only the service date span (min and max over every charge in the family), has_remit and drg_code are aggregated across the family. AR balances are taken from the attribute claim, because summing a rebill and the claim it replaced would double-count.

Who gets in. A family is published only if its location, provider, practice and TIN all resolve to masters that are not hidden, and its primary coverage is not a package Athena types as non-insurance (payer.noninsurancetype). Every other family goes to excluded_encounter with a reason. tests/encounter_population_reconciles.sql checks that each family lands in exactly one of the two.

Claim

"A coordination position on an athena claim": one row per (claim, cob), built in stg_claim_position.sql and claim.sql. claim_id = sk([source_claim_id, cob]), so one Athena claim produces up to three rows and source_claim_id alone is not unique.

• "Configured" means is_configured_slot(): not null, not blank, and not the '0' sentinel.
• Positions are independent. A claim can be billed secondary with no primary, so nothing may assume cob 1 exists before reading cob 2.
• is_billed marks a position that was actually submitted. Unbilled positions are kept because payers remit against positions that were never billed.
• is_effective marks the live row for each (family, cob): the latest submission, with billed positions ahead of configured-only ones.
• parent_claim_id points to the root claim at the same cob, and is set only on rebills. frequency_code comes from medicaidresubmissioncode, else original for the root and replacement otherwise.
• Remits find their position by matching patientinsuranceid against the claim's slots (stg_claim_coverage_slot), never by date. A policy at two slots ranks primary, then secondary, then patient.

Service line

"A single billed service within an encounter": one row per non-voided CHARGE transaction (stg_tx_charge.sql, service_line.sql). service_line_id = sk(parentchargeid), the same id space as erarecord.chargeid, which is how remits attach to a line. The line records only what was billed; payer answers live in service_line_adjudication.

• claim_id attaches to one position only: the claim's billed position, trying primary, then secondary, then patient. If the claim was never submitted, it is null and the line stays on its encounter.
• line_number is a display ordinal by charge id. Athena has no LX line number or REF*6R control number.
• Procedure code and modifiers are split once from Athena's compound code (for example 99213,25,59) plus othermodifier. Modifier 99 sets modifier_overflow.
• Units are replaced with timesheet minutes for anesthesia.

Payer answers and money

Gold (shared/dbt-medallion/models/gold) keeps these grains one to one. dim_/fact_encounter is one row per encounter, dim_claim one row per position (unbilled included), dim_/fact_service_line one row per charge, and each *_adjudication model one row per (grain, cob). The calculation facts are one row per (encounter or line, run, scenario). fact_encounter_variance covers only scored encounters, and only against cob 1.

Keys

• sk() hashes in the source system and tenant: md5('athena:' || context_id || ':' || id). Athena ids are unique only within one context, so never join on a bare Athena id.
• global_key() is unscoped and used only for identities the outside world assigns (TIN, address), so one real entity reached from two systems lands on one row.
• The legacy pipeline uses a different grain. A legacy account is a clinical encounter or appointment (transform_account_grain), with a <claimid>-CLAIMONLY fallback, keeping one claim per account. encounter.legacy_account_id maps between them, but several families on one appointment can share a value.

PART 2Master entities

Four entity types are mastered: location, provider, practice and billing entity (TIN). Master IDs are attached all through silver and gold. Master attribute values are read in only a few places. Much of an encounter's context still comes straight from Athena.

Where masters come from

The checked-in crosswalks hold 151 location, 316 provider, 1 practice and 2 TIN rows. hidden_master.csv lists 9 locations, all with reason "AllyMed".

Where master IDs attach

In gold, the fact_* models carry these IDs forward from encounter, or from service_line for line-grain facts. The encounter's scopes column ([location_id, practice_id]) drives row-level access on every gold model.

Where master values are read

Where source values are used instead

entity_encounter would mix both kinds (source department_name beside master city and state), but it is disabled and isn't built.

PART 3Scored attributes

Rule set selection runs in dbt silver, before the pricing scorer. encounter_rule_set_score scores every (encounter, cob) against every rule set's include and exclude lists. The pricing scorer (defs/pricing/assets.py with shared/pricing-scorer) reads the candidates above its consistency threshold and resolves calculations from them.

The attribute set

Defined by three macros in projects/commonwealth/dbt/macros/. scored_attributes() joins them in this order. Weights are versioned by scoring_weight_version: "2026-09-24" and scoring_algo_version: "1.5.0" in dbt_project.yml.

Where each value comes from

encounter_coverage_resolved.sql is the input contract: one row per (encounter, cob) with a service date.

For each routing target, the matching rule with the lowest priority wins. The rule that fired is recorded in source_payer.routing_evidence as JSON, which Phoenix shows. The payer, line-of-business and plan-type vocabularies are generated from shared/payer-reference/payers.json.

Normalization

macros/scored_attribute_value.sql reduces each value to one comparable form. The encounter side and the rule set selector side both pass through it (normalized_selector_values()), so the two vocabularies can't drift. A value that doesn't fit its shape becomes null; it is never forced into one.

How scoring works

• Matching (selector_matches()): plan_descriptor matches if the value contains any listed substring. Every other attribute needs an exact match.
• Credit: a match earns 1.0 and a miss 0. zip_code earns 0.5 when the first three digits match. A null value earns no credit and counts as unknown weight.
• Gates: every exclude drops the encounter. Only coverage includes gate. A null coverage value passes its include as unknown only when the payer resolved; an unresolved payer is admitted only by an include that names 'unresolved'.
• Outputs: consistency = match_score / applicable_weight; completeness = applicable / (applicable + unknown); identity_confirmed is true when any coverage attribute matches; attribute_outcomes lists match, conflict, partial or unknown per attribute. Rows with zero applicable weight are dropped.

Other derived fields

• care_setting: a CASE over placeofservicetype in stg_department.sql (asc, outpatient_hospital, inpatient_hospital, office).
• opportunity_classification(): No Response, Denial, Underpayment or No Opportunity, with the threshold from org.underpayment_threshold.
• procedure_code_system(): CPT, HCPCS or LOCAL by code range and pattern.
• resolved_encounter_money(), primary_allowed_by_encounter() and denied_amount_by_encounter(): the money measures behind fact_encounter_variance.payment_variance and variance_pct.

PART 4Phoenix

Phoenix is the RevFind app: a .NET API and a React web app over the customer's gold layer. Its docs say gold "arrives precomputed" and that pricing math belongs to the medallion stack. In practice Phoenix owns a set of rules of its own, and in several places it recomputes something gold already publishes, sometimes with a different answer.

What it reads and writes

Phoenix reads gold only, through DuckDB over parquet (src/Phoenix.Infrastructure/DataLake/GoldDbContext.cs). It reads no silver and none of the star schema. Every read is scoped by the row's scopes array: a caller sees a row if any of their practice or location ids is in it.

Each write is a full snapshot to landing/mdc/dt=YYYY-MM-DD/ in the customer bucket. Notes, projects, packages, outcomes, lump sums and templates are not written back, so gold doesn't see them.

Three opportunity rules

"Is this encounter an underpayment or a denial?" is answered three ways, and none of them reads gold's opportunity_type.

The gold and Phoenix rules measure different gaps. Gold compares what the payer allowed with what it paid. Phoenix compares what we expected with what the payer allowed. They can agree on an encounter by coincidence, but they are not two versions of one rule. The threshold value is the same number in both places, because Phoenix writes it to the lake, but each side reads its own copy.

Phoenix's rule decides real behavior: the search filter, the opportunity badges on the encounter page, whether an encounter can join a project, and whether the appeal deadline is shown at all.

Where Phoenix reimplements gold

Rules Phoenix owns

These have no gold equivalent. Most are platform state that gold deliberately leaves out (fact_encounter_variance.sql says validated opportunity and appeal state are "platform state").

• Recovered amount, two ways. Encounter page, project stats and the appeal package use actual_reimbursement − initial_allowed_amount, the change since the payer's first answer. The Recovery page uses current allowed minus allowed as of the filing date. Lump sums are added to project stats and listed separately on the Recovery page.
• Validated opportunity. Sum of payment_variance for project members past In Review and still active.
• Project payer. A project appeals one payer: the most common cob-1 payer_id among its members. Candidates with a different or unresolved payer are rejected.
• Appeal eligibility. One active project per appeal type per encounter, and the encounter must pass Phoenix's opportunity rule for the project's type.
• Appeal stages. 19 stages, a three-level ladder plus legal, and "a spent level is never reused." Manual stage changes skip the ladder rules on purpose.
• Source payer to payer mapping. Built from cob-1 coverage rows, because dim_source_payer has no payer_id. The join uses the insurance id alone, without the source system.
• Age at service in whole years, with a 90+ band when PHI is masked, and an age filter in search.
• Appeal package CSV. "Practice" is filled with the billing entity name or TIN. "Geography" is always blank, though dim_encounter.dos_state exists; it just isn't on encounter_details.

Phoenix as the stewardship writer

Phoenix is where master entities are created and edited (Part 2). The pipeline folds the ledger the same way Phoenix does: latest event by occurred_at desc, id desc. The payload keys mostly match, with two gaps.

• Phoenix never writes the crosswalk. Silver keeps a master only if a checked-in crosswalk/*.csv row points at it. A location created in Phoenix stays out of silver and gold until someone edits a CSV in the repo, and the ledger itself reaches the lake only when someone presses the push button.
• Phoenix validates state codes, ZIP (^\d{5}(-\d{4})?$), 10-digit NPIs, taxonomy shape, and TINs (^\d{2}-?\d{7}$). Location, practice and provider names allow only letters, digits, spaces and periods, so &, apostrophes, hyphens, commas and slashes are rejected.
• Phoenix matches locations by name, not id. The location picker and the search location filter join gold location_name to Phoenix locations by normalized name (LocationEndpoints.cs:59-71, GoldEncounterSearch.cs:56-57), though gold carries location_id in scopes.
• Appeal stages lose their project in gold. Phoenix tracks stage per (project, encounter). Gold fact_encounter keeps one stage per encounter with arg_max(appeal_stage, stage_changed_at), so an encounter in two projects shows whichever changed last.

Rules in the web app

The React app (web/src/) adds another layer. Some of it duplicates server rules; some is found nowhere else.

PART 5Findings

Things that look inconsistent, unverified, unused or wrong. Some may be intentional; most need a decision about which side is right before anything is fixed.

Pipeline

Phoenix