Patient Taxonomy

Taxonomy is Elix's governed classification layer. A facility organises patients, clinic departments and patient lists into dimensions of controlled terms: care programmes, service pathways, care priority, access and support needs, population cohorts. Reports filter and group by them. Taxonomy is operational: it never replaces diagnoses, observations, safeguarding notes or statutory reporting, which stay in the clinical record.

Concepts

• Dimension: a controlled question with a stable key, such as care-programme. A dimension declares whether a patient may carry one term or several, and what it applies to: patients always, and optionally clinic departments and patient lists.
• Term: one answer in a dimension, with a stable code, a colour, optional hierarchy (a parent term), synonyms, a link to an external standard, and a display order.
• Assignment: a term attached to a patient, department or list. Patient assignments record who made them, why, and the window they are in force; ending one keeps the history.
• Privacy class: a sensitive term (HIV care, reproductive health, mental health, genetic, VIP) is marked as such. Analytics and reports withhold exact counts for a sensitive term carried by fewer than five patients.
• Review: a term can require periodic review at an interval the facility sets.

Where taxonomy appears

Surface	What you can do
Administration → Taxonomy	Manage dimensions and terms: create, edit, archive and restore terms; set a dimension's selection rule and what it applies to; install recommended presets; see where a term is used and end assignments in place.
Patient record → Classifications	See every term in force on the patient with when it started, until when and why; assign or end terms with a note and an end date.
Patient registration	Pick classifications while registering or editing a patient; one-per-patient dimensions behave as a choice.
Patients register	Filter the register by classification.
Patient Setup → Lists	Classify a list, and add every patient carrying a term to a list in one step.
Clinic departments	Attach service-pathway terms so registration and encounter billing route by pathway.
Reports	Patients reports accept classification, dimension and cohort-type filters; the Taxonomy Breakdown report counts patients, departments and lists per term.

Recommended presets

Elix ships a starter catalogue for African care providers: clinic service pathways (GOPD, Accident and Emergency, Ophthalmology, Antenatal, NHIA, Surgical Outpatient, Immunisation, Physiotherapy), care programmes (antenatal, postnatal, under-five, immunisation, HIV, TB/DOTS, sickle cell, NCD), care priority, access and communication support, population cohorts and restricted public-health follow-up. Presets install idempotently, one dimension at a time, and a facility can add or archive terms without changing the shared catalogue.

Rules worth knowing

• Only assignments in force count: on the patient, in the register filter, in list population and in every report. An ended or replaced term is history, not a label.
• Assigning a term in a one-per-patient dimension replaces the term the patient already carries in that dimension; the replaced assignment is ended with the reason recorded.
• Archiving a term stops new assignments and keeps existing history; an archived term can be restored.
• Every assignment change is written to an append-only ledger, so the sequence of classifications on a patient can be reconstructed for audit.

Permissions

Taxonomy is governed by the patients.tags.* permission family: listing and reading terms; creating, updating and archiving them; and listing, adding and removing assignments. The newer patients.taxonomies.read, patients.taxonomies.manage and patients.taxonomies.assign permissions are accepted alongside them, so a role can be given the narrower "may apply a term but not invent one" split.