Clinical Foundation — How it works

Overview

The clinical engine records the core clinical record: visits and the encounters within them, coded observations, the problem list (diagnoses, conditions, allergies), clinical notes and care plans, and a patient clinical summary. It is concept-backed and references patients by id (logical, no cross-engine FK); dates and statuses are relational and indexed for query.

Data model & ownership

Table	Purpose
visit	A patient visit; relational status (ACTIVE/ENDED), start/stop.
encounter	An interaction within a visit.
observation	A coded observation (concept-bound).
diagnosis / condition / allergy	Problem list, with certainty/severity/status.
clinical_note / care_plan	Narrative + plans.

Key rules & invariants

• A visit is ACTIVE from creation until ended; encounters/observations attach to it.
• Clinical facts bind to concept ids; statuses (ClinicalStatus, DiagnosisCertainty, AllergyCategory/AllergySeverity, CarePlanStatus) are relational.
• Reads are access-scope filtered; the patient reference is logical (owned by demographic).

API

See the API Reference. Endpoint groups under /api/v1/clinical: visits, encounters, observations, diagnoses, conditions, allergies, notes, care plans, and the patient clinical summary.

Configuration & feature flags

None (clinical PHI encryption is a future follow-up beyond SEC-001).

Related features

• Concept, Demographic (patient), Program (enrollment context). Domain plug-ins read via exchange.client.clinical.