Demographic (Person, Patient, Provider) — How it works
Overview
The demographic engine owns the platform's people: the person master record and the patient and
provider roles layered on top, plus a person's names, addresses, identifiers, attributes, and
relationships. It is a generic identity foundation — no clinical knowledge — that other engines
reference by id (logical references, no cross-engine FK). It validates geography references
in-process against the metadata engine.
Data model & ownership
Owned tables (migrations under core/src/main/resources/db/changelog/demographic/):
| Table | Purpose |
|---|---|
person | Master person record; tenant-scoped; gender/birth date. |
person_name | Names (given/middle/family, prefix/suffix); one preferred per person. PII fields encrypted at rest — see below. |
person_address | Addresses; logical geography ids (country…community) validated via metadata; line1/line2/postal_code encrypted at rest. |
person_identifier_type / person_identifier | Identifier types + values, with uniqueness scope. |
person_attribute_type / person_attribute | Typed attributes (JSONB value); the encrypted flag marks sensitive types (e.g. phone). |
person_relationship | Directed person-to-person relationships. |
patient / provider | Roles on a person; provider carries code + facility assignments. |
Key rules & invariants
- One preferred name and one preferred address per person (service logic + partial unique index).
- Geography ids on an address must form a valid country → state → county → city → community hierarchy.
- Cross-engine references (e.g. a clinical visit's
patient_id) are logical — no FK across engines. - PII is encrypted at rest when enabled (SEC-001): the services encrypt names, address lines + postal code, and phone-type attribute values before save and decrypt after fetch; name/phone search uses a blind index. See PII encryption at rest.
API
See the API Reference. Endpoint groups under /api/v1/demographic: persons, patient
and provider roles, names, addresses, identifiers, attributes, relationships, and demographic search
(GET /persons?..., paginated search).
Configuration & feature flags
- PII encryption toggles (
pii.encryption.*) — see the PII encryption operations page.
Related features
metadata(geography validation),access-control/identity-access(who may see a person),clinicalandprogram(reference patients by id),concept(attribute value coding).