ohcnetwork · github-actions · Aug 9, 2026
diff --git a/docs/references/clinical/condition.mdx b/docs/references/clinical/condition.mdx
@@ -0,0 +1,130 @@
+---
+sidebar_position: 2
+---
+
+# Condition
+
+Technical reference for the `Condition` module in Care EMR.
+
+**Source:** [`care/emr/models/condition.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/models/condition.py) · [`care/emr/resources/condition/spec.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/condition/spec.py)
+
+## Overview
+
+A **Condition** records a clinical problem, diagnosis, or concern linked to a patient and an encounter. It is aligned with the FHIR `Condition` resource.
+
+## Enumerations
+
+### `ClinicalStatusChoices`
+
+| Value | Meaning |
+| --- | --- |
+| `active` | Condition is ongoing |
+| `recurrence` | Has occurred again after remission |
+| `relapse` | Returning after a period of improvement |
+| `inactive` | No longer active |
+| `remission` | Symptoms are absent but not fully resolved |
+| `resolved` | Condition is no longer present |
+| `unknown` | Status cannot be determined |
+
+### `VerificationStatusChoices`
+
+| Value | Meaning |
+| --- | --- |
+| `unconfirmed` | Awaiting confirmation |
+| `provisional` | Preliminary diagnosis |
+| `differential` | One of several possible diagnoses |
+| `confirmed` | Definitively established |
+| `refuted` | Ruled out |
+| `entered_in_error` | Recorded in error |
+
+### `CategoryChoices`
+
+| Value | Meaning |
+| --- | --- |
+| `problem_list_item` | Long-term problem on the patient's problem list |
+| `encounter_diagnosis` | Diagnosis made during a specific encounter |
+| `chronic_condition` | Ongoing chronic condition |
+
+### `SeverityChoices`
+
+| Value | Meaning |
+| --- | --- |
+| `mild` | Low clinical impact |
+| `moderate` | Significant impact requiring management |
+| `severe` | Serious or life-threatening |
+
+## Write spec (`ConditionSpec`)
+
+Used when **creating** a new condition.
+
+| Field | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `clinical_status` | `ClinicalStatusChoices` | No | Defaults to null |
+| `verification_status` | `VerificationStatusChoices` | **Yes** | |
+| `severity` | `SeverityChoices` | No | |
+| `code` | `ValueSetBoundCoding` | **Yes** | Must match `CARE_CONDITION_CODE_VALUESET` |
+| `encounter` | `UUID4` | **Yes** | UUID of an existing encounter; patient is derived from it |
+| `category` | `CategoryChoices` | **Yes** | |
+| `onset` | `ConditionOnSetSpec` | No | See below |
+| `abatement` | `ConditionAbatementSpec` | No | See below |
+| `note` | `str` | No | Free-text clinical note |
+
+### `ConditionOnSetSpec`
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `onset_datetime` | `datetime` | Cannot be in the future |
+| `onset_age` | `int` | Age in years at onset |
+| `onset_string` | `str` | Free-text description when exact date is unknown |
+| `note` | `str` | |
+
+### `ConditionAbatementSpec`
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `abatement_datetime` | `datetime` | |
+| `abatement_age` | `int` | |
+| `abatement_string` | `str` | |
+| `note` | `str` | |
+
+## Update spec (`ConditionUpdateSpec`)
+
+Used when **updating** an existing condition. Same as `ConditionSpec` except `encounter` and `category` are not included (the condition's encounter and category cannot be changed after creation).
+
+## Read spec (`ConditionReadSpec`)
+
+Returned when **reading** a condition.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | `UUID4` | External ID of the condition |
+| `clinical_status` | `str` | |
+| `verification_status` | `str` | |
+| `category` | `str` | |
+| `severity` | `str` | |
+| `code` | `Coding` | |
+| `encounter` | `UUID4` | UUID of the linked encounter |
+| `onset` | `ConditionOnSetSpec` | |
+| `abatement` | `ConditionAbatementSpec` | |
+| `note` | `str` | |
+| `created_by` | `dict` | Audit: user who created the record |
+| `updated_by` | `dict` | Audit: user who last updated the record |
+| `created_date` | `datetime` | |
+| `modified_date` | `datetime` | |
+
+:::note Breaking change
+The `criticality` field was **removed** from `ConditionReadSpec` in [ohcnetwork/care#3729](https://github.com/ohcnetwork/care/pull/3729). API clients that previously consumed this field will no longer receive it in responses.
+:::
+
+## API integration notes
+
+- Conditions are linked to both a patient and an encounter. The patient is derived automatically from the encounter on create.
+- `code` must be a coding from the configured `CARE_CONDITION_CODE_VALUESET` — typically ICD-10 or SNOMED CT codes depending on your deployment.
+- Use `category: encounter_diagnosis` for diagnoses made during a visit and `category: problem_list_item` for ongoing concerns tracked on the problem list.
+- For chronic conditions that span encounters, use `ChronicConditionUpdateSpec` which accepts an `encounter` field to associate the chronic condition with a new encounter.
+
+## Related
+
+- Reference: [Patient](./patient)
+- Reference: [Encounter](./encounter)
+- Source: [condition/spec.py on GitHub](https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/condition/spec.py)
diff --git a/docs/references/clinical/encounter.mdx b/docs/references/clinical/encounter.mdx
@@ -0,0 +1,105 @@
+---
+sidebar_position: 3
+---
+
+# Encounter
+
+Technical reference for the `Encounter` module in Care EMR.
+
+**Source:** [`care/emr/models/encounter.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/models/encounter.py) · [`care/emr/api/viewsets/encounter.py`](https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/encounter.py)
+
+## Models
+
+| Model | Purpose |
+| --- | --- |
+| `Encounter` | Core encounter record — a clinical visit or admission |
+| `EncounterOrganization` | Links an encounter to a `FacilityOrganization` |
+
+All models extend `EMRBaseModel` (shared Care EMR base with `external_id`, audit fields, and soft-delete semantics).
+
+## `Encounter` fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `status` | `CharField(100)` | Current encounter status |
+| `status_history` | `JSONField` | History of status transitions |
+| `encounter_class` | `CharField(100)` | Class of encounter (e.g. inpatient, outpatient, emergency) |
+| `encounter_class_history` | `JSONField` | History of class changes |
+| `patient` | `FK → Patient` | The patient this encounter belongs to |
+| `facility` | `FK → Facility (PROTECT)` | Facility where the encounter takes place |
+| `appointment` | `FK → TokenBooking (SET_NULL)` | Optional link to a scheduled appointment |
+| `period` | `JSONField` | Start and end datetime of the encounter |
+| `hospitalization` | `JSONField` | Hospitalization-specific details |
+| `priority` | `CharField(100)` | Clinical priority level |
+| `external_identifier` | `CharField(100)` | External system identifier for this encounter |
+| `care_team` | `JSONField` | List of care team members (`user_id`, role, etc.) |
+| `care_team_users` | `ArrayField[int]` | Denormalized cache of user IDs from `care_team` |
+| `facility_organization_cache` | `ArrayField[int]` | Denormalized cache of organization IDs for filtering |
+| `current_location` | `FK → FacilityLocation (SET_NULL)` | Current ward/bed location of the patient |
+| `discharge_summary_advice` | `TextField` | Clinical discharge advice text |
+| `tags` | `ArrayField[int]` | Tag IDs applied to this encounter |
+| `extensions` | `JSONField` | Open extension bag for deployment-specific metadata |
+
+## `EncounterOrganization`
+
+Links an encounter to a facility organization for access control and reporting.
+
+```text
+encounter     → FK Encounter
+organization  → FK FacilityOrganization
+```
+
+Saving an `EncounterOrganization` triggers `encounter.sync_organization_cache()`, which rebuilds the encounter's `facility_organization_cache`.
+
+## Methods & save behaviour
+
+### `sync_care_team_users_cache()`
+
+Rebuilds `care_team_users` from the `care_team` JSON list on every `save()`. Integrators writing directly to `care_team` must call `save()` to keep the cache consistent.
+
+### `sync_organization_cache()`
+
+Rebuilds `facility_organization_cache` by collecting all organizations linked via `EncounterOrganization` plus their parent chains and the facility's default internal organization. Called automatically on `save()`.
+
+### `save()` side effects
+
+On every save:
+
+1. `sync_care_team_users_cache()` runs (updates `care_team_users`)
+2. The record is persisted
+3. On **create only** — `evaluate_patient_facility_default_values()` runs to generate facility-scoped patient identifiers
+4. `sync_organization_cache()` runs and issues a second `save(update_fields=[...])` to persist the cache
+
+Integrators should expect **two write passes** when creating or updating encounters through the ORM.
+
+## API actions
+
+### `POST /api/v1/encounter/{id}/set_facility_identifier/`
+
+Sets or deletes a facility-scoped patient identifier for the encounter's patient at the encounter's facility.
+
+**Request body** (`EncounterFacilityIdentifierWriteSpec`):
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `identifier_config` | `UUID4` | UUID of a `PatientIdentifierConfig` scoped to this facility |
+| `value` | `str \| None` | The identifier value; pass `null` to delete the identifier |
+| `set_default` | `bool` | If `true`, sets this config as the default for the facility |
+
+**Requires:** update permission on the encounter.
+
+:::note Breaking change
+This endpoint was renamed from `set_facility_idenitifier` (with a typo) to `set_facility_identifier` in [ohcnetwork/care#3730](https://github.com/ohcnetwork/care/pull/3730). The DRF URL pattern changes from `encounter-set-facility-idenitifier` to `encounter-set-facility-identifier`. Clients using the old URL must update their requests.
+:::
+
+## API integration notes
+
+- `extensions` is the supported place for custom key-value data without schema migrations.
+- `care_team_users` and `facility_organization_cache` are maintained by the platform — do not set them directly from clients.
+- Use `EncounterOrganization` to associate encounters with organizations; the cache is rebuilt automatically.
+
+## Related
+
+- Reference: [Patient](./patient)
+- Reference: [Condition](./condition)
+- Source: [encounter.py on GitHub](https://github.com/ohcnetwork/care/blob/develop/care/emr/models/encounter.py)