Access computed from contracts, not from a tenant column.

A closure table pre-computes every ancestor and descendant pair, so the question 'which entities can this user reach' is an indexed lookup rather than a recursive walk at request time. Relationship types are first-class values — hierarchy, delegation, contract, value-based contract, contracted provider — which means a delegation is a row you can query, expire and audit, not a boolean on an organization.

Writes to the graph are all-or-nothing. Creating a relationship inserts the self-link and one row per ancestor of the new parent inside a single transaction or nested savepoint, so a partial closure state cannot be observed by a concurrent reader. The inserts use MySQL's INSERT IGNORE, which makes re-running the operation against already-seeded rows safe rather than an error.

• entity_type has exactly one source of truth — the MySQL enum. A test fails the whole suite if the Pydantic literal, the frontend list or the docs drift from it.
• A third table, entity_data_access, holds per-user grants: role, permissions, delegated scopes and reachable entity ids, unique per user, entity and role.

The entity a user is currently acting as is read from the token, not the database row, which is what makes entity switching a token refresh rather than a write. Authorization then fast-paths when the token's entity matches the route's entity, and otherwise falls back to scanning the user's access grants and the entity ids they reach.

The discipline that matters most is negative: routers read entity_id exclusively from the decoded token and never from the request body or a path parameter a caller controls. Several router modules state this in their own docstrings, because it is the rule that a well-meaning patch is most likely to break.

• Cross-entity reads return 404, never 403 — a caller cannot use the error code to confirm that a record exists.
• A login miss runs a real bcrypt comparison against a fixed decoy hash, closing a timing gap that would otherwise reveal which clinician email addresses are real accounts.

Every mutation writes an append-only audit row — created, updated, deactivated, reactivated — carrying a JSON diff of what changed. Nothing updates or deletes that table. The delegation history is therefore reconstructable from the log rather than inferred from the current state of the agreement.

Visibility follows from the same record. A viewer sees an IPA if it is their own entity, or if an active or pending delegation exists between that IPA and the viewer's organization. Anything else is a 404. There is no separate sharing setting to get out of sync with the contract, because the contract is the sharing setting.

Appeals are modeled as their own workflow with escalating levels, up to external review. An overturned appeal deliberately does not auto-flip the parent review's status; an explicit re-determination is required, so the record shows a human making the decision rather than a cascade doing it silently.

SLA urgency is computed on read from the deadline rather than stored: more than 48 hours out reads as on track, 8 to 48 hours as due soon, under 8 hours or past as overdue. Storing it would mean a row could be wrong simply because time passed. A background job sweeps submitted and in-review authorizations against their deadlines every five minutes and writes a heartbeat, so a health endpoint can report the sweep itself as stale after ten minutes — a dead man's switch for the job, not just for the container.

• Re-determining an already-decided review returns 409 rather than quietly overwriting the decision.
• List endpoints cap page size server-side, so a caller cannot request the whole table in one page.

The claim row carries the full financial breakdown — billed, allowed, paid, balance, adjustment and non-covered amounts — alongside the CMS-1500 and UB-04 fields the forms actually require, mapped to named columns rather than a generic blob. Line items, denial categorisation, remittance and payment allocation live in companion tables so a claim's history is queryable rather than serialized.

Human-readable display identifiers are generated per entity, not globally. That avoids a single global counter becoming a contention point, and it means two organizations can each have their own CLM-00001 without collision.

The broader NCQA lifecycle is modeled on the provider entity itself: not started, draft, submitted, in PSV, committee review, approved, active, then expired or suspended, with a recredentialing due date on the standard 36-month cycle.

The gap is stated in the code rather than hidden: there is no automated registry integration. A verification query is recorded as pending and a human reviewer resolves it to passed or failed once the registry result is back. The system organizes and evidences the work; it does not pretend to have queried NPDB for you.

That consolidation followed a real defect, and the module documents it. Three separate call sites had each computed the score their own way — one of them stored only the summed condition weights and labelled it as the full formula, which put an incorrect score on a client-facing report. The fix was not a patch at the call site; it was routing the encounter-sign recompute, the interactive calculator and every panel and risk-tier display through one function.

It is worth reading that as a statement about how this codebase treats correctness. A number that appears in three places will eventually be three different numbers unless something structural prevents it.

Separately, mutating actions write an audit event capturing the actor, IP address, user agent and request id, pulled from request context rather than passed in by the caller. The model documents its own history here too: sixteen direct-construction call sites had been leaving the IP address empty on every row until a column-level default closed the gap.

Immutability of the audit log is currently enforced by application convention rather than by a database trigger. That is stated in the model comment as a known future goal, and it is stated here for the same reason.