-
Notifications
You must be signed in to change notification settings - Fork 1
Glossary
This page defines the clinical, billing, and interoperability vocabulary a developer will hit in this codebase, with the model or column each term maps to. It is for anyone who can read the code but not the domain.
The vocabulary is the steepest part of this repository for most developers, and none of it is hard once named.
Appointment. A booked slot: a patient, a provider, a facility, a start and end. Model: Appointment. Its status moves through a long enum from PROPOSED to BOOKED, ARRIVED, CHECKED_IN, ROOMED, IN_PROGRESS, CHECKED_OUT, and either FULFILLED, CANCELLED, or NOSHOW.
Encounter. The visit itself, as a clinical event. Created automatically on check-in from the appointment, and holds a one-to-one link back to it. Everything clinical hangs off the encounter, not the appointment: notes, diagnoses, orders, charges. Model: Encounter.
The distinction matters. An appointment is a plan. An encounter is what happened. A patient can have an encounter with no appointment (a walk-in), and an appointment that never becomes an encounter (a no-show).
Encounter class. Where care happened: ambulatory, virtual, home, field, emergency. Enum: EncounterClass.
Check-in. The front-desk act of marking a patient present. It creates the encounter and starts the clock the flow board displays.
Flow board. The live view of who is in the building and what state they are in, with wait timers. Backed by AppointmentStatusHistory rather than by a separate timing table, so the timers derive from recorded transitions.
Rooming. Moving a patient from the waiting area into an exam room, usually with vitals captured on the way.
Chart. Everything recorded about one patient. Not a table; a view assembled from many.
MRN, medical record number. The identifier a practice uses for a patient internally. Unique within an organisation, not globally. Column: Patient.mrn, with @@unique([tenantId, mrn]). Every other identifier lives in PatientIdentifier.
Problem list. The patient's active and historical diagnoses, maintained over time rather than per visit. Model: Condition with category PROBLEM_LIST_ITEM.
Encounter diagnosis. A diagnosis recorded for one specific visit, which is what a claim is built from. Model: Condition with category ENCOUNTER_DIAGNOSIS.
Clinical note. The document describing a visit. Stored as a block list in JSON rather than as HTML or a filled template. Model: ClinicalNote.
Signing. A clinician attesting to a note. A signed note is immutable.
Addendum. A correction to a signed note, added as a new record rather than an edit. Model: NoteAddendum. This is why signing matters structurally rather than just as a workflow step.
Cosign. A second clinician's signature on another's note, typically supervisory. Columns: ClinicalNote.cosignerId and cosignedAt.
Vitals. Blood pressure, pulse, temperature, weight, and so on. Model: Observation with category VITAL_SIGNS.
Medication statement versus medication request. A statement is what the patient reports taking, including prescriptions from elsewhere. A request is a prescription this practice wrote. Two different facts, two models: MedicationStatement and MedicationRequest.
Sig. The dosing instruction on a prescription, from the Latin signa. "One tablet by mouth twice daily." Stored twice on purpose: structured in MedicationRequest.sig and rendered as text in sigText.
Reconciliation. Comparing what a patient is actually taking against what the record says, and resolving the difference. Enum value: MedicationSource.RECONCILED.
Order. A request for something to be done: a lab test, an imaging study, a procedure, a referral, or therapy. All five are one model, ServiceRequest, split by category.
Ask-at-order-entry. Questions a lab requires when an order is placed, such as the date of a last menstrual period for certain tests. Column: ServiceRequest.aoeAnswers.
Specimen. The physical sample collected for a test. Model: Specimen, with the accession number the lab uses to track it.
Accession number. The lab's identifier for a specimen. Unique within an organisation.
Diagnostic report. The result document a lab or imaging centre returns. Model: DiagnosticReport.
Result observation. One discrete analyte inside a report, for example the sodium value within a metabolic panel. Model: ResultObservation, sequenced within its report so lines cannot orphan.
Reference range. The range a result is considered normal within, which varies by analyte, sex, and age. Columns: referenceLow and referenceHigh.
Abnormal flag. Whether a result is normal, abnormal, or critical. Enum: AbnormalFlag. Critical values are excluded from bulk sign-off, deliberately.
Sign-off. A clinician reviewing and acknowledging a result. Columns: DiagnosticReport.reviewedById and reviewedAt. The index on those columns is the unreviewed-results queue.
CPT, Current Procedural Terminology. Codes for procedures and services performed. What a practice bills for. Five digits, for example 99213 for an established-patient office visit. Default code system on ChargeItem.
HCPCS, Healthcare Common Procedure Coding System. Codes for things CPT does not cover: supplies, drugs, durable equipment, some services.
Modifier. A two-character suffix on a procedure code that changes its meaning without changing the code, for example marking a service as distinct from another performed the same day. Column: ChargeItem.modifiers.
ICD-10-CM. Diagnosis codes. What was wrong, as opposed to what was done. E11.9 is type 2 diabetes without complications. Default code system on Condition.
SNOMED CT. A large clinical terminology, more expressive than ICD-10-CM and used for clinical rather than billing purposes. Licence-restricted, which is why openrunic never vendors it.
LOINC, Logical Observation Identifiers Names and Codes. Codes for observations and lab tests: what was measured. Default code system on Observation.
RxNorm. Normalised medication names, so that a brand and its generic map to the same concept. Column: MedicationStatement.rxnormCode.
NDC, National Drug Code. Identifies a specific manufactured drug package.
CVX and MVX. Vaccine codes and vaccine manufacturer codes. Columns on Immunization.
UCUM, Unified Code for Units of Measure. The unit standard for observation values. mg/dL, mmol/L.
All of these except the closed HL7 value sets are stored as plain strings with a codeSystem string alongside, never as database enums, because terminology is licensed and evolving. See Compliance posture.
NPI, National Provider Identifier. A ten-digit identifier for a clinician or an organisation in the US. Columns: User.npi and Facility.npi.
DEA number. The registration that allows a clinician to prescribe controlled substances. Column: User.dea.
Taxonomy code. A code identifying a provider's specialty. Column: User.taxonomyCode.
Place of service. A two-digit code saying where a service happened, which affects reimbursement. 11 is an office, 02 is telehealth. Columns: Facility.posCode and ChargeItem.placeOfServiceCode.
Payer. The insurance company. Model: Payer.
Coverage. One insurance policy held by one patient. Model: Coverage. A patient can have several.
Coordination of benefits. The rules deciding which policy pays first when a patient has more than one. Expressed as Coverage.rank: primary, secondary, tertiary.
Subscriber. The person who holds the policy, who may not be the patient. A child is typically covered under a parent's policy. Column: subscriberRelationshipCode.
Member id and group number. The identifiers on an insurance card.
Eligibility. Checking, before or at the visit, whether a policy is active and what it covers. In the transaction sets this is a request and its response.
Copay, deductible, coinsurance. What the patient owes. A copay is a fixed amount per visit. A deductible is what the patient pays before insurance starts. Coinsurance is a percentage after that. Stored in integer cents.
Prior authorisation. Approval a payer requires before certain services. A task type in the inbox.
Accept assignment. Whether the practice agrees to accept the payer's allowed amount as full payment. Column: Coverage.acceptAssignment.
flowchart LR
A["Charge capture<br/>ChargeItem"] --> B["Scrub<br/>validate before sending"]
B --> C["Claim submitted<br/>Claim, ClaimLine"]
C --> D["Acknowledged<br/>ClaimStatusHistory"]
D --> E{Adjudicated}
E -->|paid| F["Remittance<br/>Remittance, RemittanceLine"]
E -->|denied| G["Denial<br/>appeal or rebill"]
F --> H["Post<br/>Payment, PaymentAllocation"]
H --> I["Patient balance<br/>Statement"]
G --> C
Charge capture. Recording what was done so it can be billed. Model: ChargeItem.
Fee sheet. The screen where a clinician or coder records the charges for a visit.
Superbill. The itemised summary of a visit's diagnoses and procedures. Historically a paper form handed to the patient or the biller; here it is the set of charge items and diagnoses for an encounter.
Diagnosis pointer. The link from a billed procedure to the diagnosis that justifies it. Stored as one-based indices into the claim's diagnosis list, matching the corresponding claim field. Column: ChargeItem.diagnosisPointers.
Justification. Making sure every billed line points at a diagnosis that supports it. A claim with an unjustified line will be denied, which is why the fee sheet refuses to mark a sheet ready without one.
Scrubbing. Validating a claim before it is sent, to catch what would otherwise cause a rejection. Enum value: ClaimStatus.SCRUBBED.
Claim. The bill sent to a payer. Model: Claim, with one ClaimLine per service.
Professional claim. The claim format used by clinicians, as distinct from the institutional format used by facilities. @openrunic/x12 targets the professional set.
Clearinghouse. An intermediary that validates and routes claims between practices and payers. openrunic is not one and does not touch payer networks directly.
Rejection versus denial. A rejection never reached adjudication, usually a format or eligibility problem, and is fixed and resubmitted. A denial was adjudicated and refused, and is appealed or written off. Different statuses and different work.
Adjudication. The payer deciding what it will pay.
Allowed amount. What the payer says a service is worth, which is usually less than the charged amount. Column: ClaimLine.allowedCents.
Remittance advice, ERA. The payer's explanation of what it paid and why, returned electronically. Model: Remittance, with one RemittanceLine per service line.
Auto-posting. Applying a remittance to claims automatically. Lines that do not match become exception tasks rather than being dropped silently.
CARC, claim adjustment reason code. Why an amount was not paid: contractual adjustment, patient deductible, and so on. Column: adjustmentReasonCode.
RARC, remittance advice remark code. Additional explanation alongside a CARC. Column: RemittanceLine.remarkCodes.
Adjustment group code. The category an adjustment falls into: contractual obligation, patient responsibility, payer initiated, other. Column: adjustmentGroupCode.
Write-off. An amount the practice will not collect, usually a contractual adjustment.
Allocation. Applying part of a payment to a specific claim, line, or charge. Model: PaymentAllocation. A patient's balance is charges minus allocations. One ledger, no second source of truth.
Patient responsibility. What is left for the patient after insurance.
Statement. The bill sent to the patient. Model: Statement.
Dunning. The escalating sequence of reminders for an unpaid balance. Column: Statement.dunningCycle.
Ageing, AR ageing. Grouping outstanding balances by how long they have been outstanding: 0 to 30, 31 to 60, 61 to 90, 91 and over. AR is accounts receivable.
Rebill. Resubmitting a corrected claim. Enum: ClaimFrequency distinguishes original, replacement, and void.
FHIR, Fast Healthcare Interoperability Resources. The HL7 standard openrunic serves at its API boundary. Release R4, version 4.0.1. See FHIR boundary.
Resource. One FHIR object: a Patient, an Observation, a Claim. The unit a FHIR API reads and writes.
Bundle. A collection of resources. A search returns a searchset bundle.
CapabilityStatement. A machine-readable description of what a FHIR server supports. Served at /fhir/metadata, generated from the same registry that validates search parameters, so it cannot advertise something the server refuses.
OperationOutcome. FHIR's error resource.
Profile. A constrained version of a resource for a particular context, stating which fields must be supported.
US Core. The US implementation guide profiling FHIR resources for national use. The Patient resource declares its profile.
USCDI. The dataset US Core is built to carry.
SMART on FHIR. The authorization framework letting third-party applications launch against a FHIR server with scoped access. Not implemented; the CapabilityStatement names bearer security today.
Bulk data export. Extracting large datasets for population-level use. Not implemented, and the reason cursor pagination is reserved rather than used for ordinary lists.
X12. The EDI standard family used for claims, remittances, acknowledgements, and eligibility in the US. @openrunic/x12 is early work on a branch.
HL7 v2. The older messaging standard still ubiquitous for lab interfaces. Not implemented.
Purpose of use. Why a record was accessed: treatment, payment, healthcare operations. Recorded on every audit event as an HL7 code such as TREAT, HPAYMT, or HOPERAT.
Break the glass. Emergency access that bypasses a normal restriction, granted on the understanding that it is conspicuously recorded. Column: AuditEvent.breakglass, with its own index so those events can be reviewed as a set.
Sensitivity class. A marker that a record needs handling beyond the default. Column: Patient.sensitivityClass and Document.sensitivityClass.
Consent. A recorded permission: to treat, to access the portal, to share information, to participate in research, to be contacted, or a financial authorisation. Model: ConsentGrant.
Entered in error. The correct way to retract a clinical record. Clinical rows are never hard-deleted; the status transitions and an audit event records it. Appears as a value in many status enums.
PHI, protected health information. Health information that identifies a person. The thing the synthetic-data rule exists to keep out of this repository.
openrunic is an open-source operating system for human health. Pre-alpha: do not run it in production, and never put real patient data into it.
Repository · Licence (AGPL-3.0-only) · Security policy · Contributing · Code of conduct
Where this wiki and the repository disagree, the repository is right.