Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:01:06Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:31, 6 July 2026
Line 144:		Line 144:
	* <code>extensions</code> is the supported place for custom key-value data without schema migrations.		* <code>extensions</code> is the supported place for custom key-value data without schema migrations.
	* <code>users_cache</code> and <code>organization_cache</code> are maintained by the platform — do not set them directly from clients.		* <code>users_cache</code> and <code>organization_cache</code> are maintained by the platform — do not set them directly from clients.

			{{Navbox clinical}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:46:15Z

OHC identity seed

Show changes

Admin: OHC identity seed

2026-07-04T22:44:30Z

OHC identity seed

Show changes

Admin: OHC identity seed

2026-07-04T22:31:20Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Patient (reference)
|summary=Technical reference for the Patient module in Care EMR — models, fields, relationships, and save behaviour.
|order=1
|introduced=3.0
|fhir=Patient
|model=Patient
|source=care/emr/models/patient.py
|concept=Concepts/Patient
|flow=Flows/Create a patient
}}

Technical reference for the <code>Patient</code> module in Care EMR. For a product-oriented overview, see the [[Concepts/Patient|Patient concept]].

== Models ==

{| class="wikitable"
! Model !! Purpose
|-
| <code>Patient</code> || Core patient record
|-
| <code>PatientOrganization</code> || Links a patient to an <code>Organization</code>
|-
| <code>PatientUser</code> || Grants a <code>User</code> access to a patient with a <code>RoleModel</code>
|-
| <code>PatientIdentifierConfig</code> || Defines identifier types (instance-wide or per-facility)
|-
| <code>PatientIdentifier</code> || Stores an identifier value for a patient
|}

All models extend <code>EMRBaseModel</code> (shared Care EMR base with <code>external_id</code>, audit fields, and soft-delete semantics).

== <code>Patient</code> fields ==

=== Demographics ===

{| class="wikitable"
! Field !! Type !! Notes
{{Field|model=Patient|section=Demographics|name=name|type=CharField(200)|notes=Display name}}
{{Field|model=Patient|section=Demographics|name=gender|type=CharField(35)|notes=Administrative gender}}
{{Field|model=Patient|section=Demographics|name=date_of_birth|type=DateField|notes=Nullable; preferred when known}}
{{Field|model=Patient|section=Demographics|name=year_of_birth|type=IntegerField|notes=Min 1900; used when full DOB is unknown. Auto-set from <code>date_of_birth</code> on save}}
{{Field|model=Patient|section=Demographics|name=deceased_datetime|type=DateTimeField|notes=Set when patient is marked deceased; affects age calculation}}
{{Field|model=Patient|section=Demographics|name=blood_group|type=CharField(16)|notes=}}
|}

=== Contact & address ===

{| class="wikitable"
! Field !! Type !! Notes
{{Field|model=Patient|section=Contact & address|name=phone_number|type=CharField(14)|notes=Validated with <code>mobile_or_landline_number_validator</code>}}
{{Field|model=Patient|section=Contact & address|name=emergency_phone_number|type=CharField(14)|notes=Same validator}}
{{Field|model=Patient|section=Contact & address|name=address|type=TextField|notes=Current address}}
{{Field|model=Patient|section=Contact & address|name=permanent_address|type=TextField|notes=}}
{{Field|model=Patient|section=Contact & address|name=pincode|type=IntegerField|notes=Nullable}}
|}

=== Organization & access caches ===

These are '''denormalized caches''' rebuilt on every <code>Patient.save()</code> for fast filtering without deep joins.

{| class="wikitable"
! Field !! Type !! Notes
{{Field|model=Patient|section=Organization & access caches|name=geo_organization|type=FK → Organization|notes=Geographic/administrative org assignment}}
{{Field|model=Patient|section=Organization & access caches|name=organization_cache|type=ArrayField[int]|notes=Rebuilt by <code>rebuild_organization_cache()</code> — includes <code>geo_organization</code> parent chain and all linked <code>PatientOrganization</code> orgs}}
{{Field|model=Patient|section=Organization & access caches|name=users_cache|type=ArrayField[int]|notes=Rebuilt by <code>rebuild_users_cache()</code> — user IDs from <code>PatientUser</code> rows}}
|}

=== Identifiers & tags ===

{| class="wikitable"
! Field !! Type !! Notes
{{Field|model=Patient|section=Identifiers & tags|name=instance_identifiers|type=JSONField|notes=List of <code>{config, value}</code> built from <code>PatientIdentifier</code> rows (instance-scoped configs)}}
{{Field|model=Patient|section=Identifiers & tags|name=facility_identifiers|type=JSONField|notes=Dict keyed by <code>facility_id</code> → list of <code>{config, value}</code>}}
{{Field|model=Patient|section=Identifiers & tags|name=instance_tags|type=ArrayField[int]|notes=Instance-level tag IDs}}
{{Field|model=Patient|section=Identifiers & tags|name=facility_tags|type=JSONField|notes=Dict keyed by facility → tag IDs}}
{{Field|model=Patient|section=Identifiers & tags|name=extensions|type=JSONField|notes=Open extension bag for deployment-specific metadata}}
|}

Identifier values live in <code>PatientIdentifier</code> and are materialized into the JSON caches via <code>build_instance_identifiers()</code> and <code>build_facility_identifiers(facility_id)</code>.

== Related models ==

=== <code>PatientOrganization</code> ===

<syntaxhighlight lang="text">
patient → FK Patient
organization → FK Organization
</syntaxhighlight>

Saving a <code>PatientOrganization</code> triggers <code>patient.save()</code>, which rebuilds <code>organization_cache</code>.

=== <code>PatientUser</code> ===

Grants a Care user access to a patient record.

<syntaxhighlight lang="text">
user → FK User
patient → FK Patient
role → FK RoleModel (PROTECT)
</syntaxhighlight>

Saving a <code>PatientUser</code> triggers <code>patient.save()</code>, which rebuilds <code>users_cache</code>.

=== <code>PatientIdentifier</code> / <code>PatientIdentifierConfig</code> ===

<code>PatientIdentifierConfig</code> defines what identifiers exist (status, optional facility scope, JSON config). <code>PatientIdentifier</code> stores the actual value:

<syntaxhighlight lang="text">
patient → FK Patient
config → FK PatientIdentifierConfig
facility → FK Facility (nullable)
value → CharField(1024), indexed
</syntaxhighlight>

<code>PatientIdentifierConfigCache</code> provides in-process caching for configs (<code>get_instance_config()</code>, <code>get_facility_config(facility_id)</code>).

== Methods & save behaviour ==

=== Age ===

* <code>get_age() → str</code> — human-readable age (years, months, days) relative to <code>deceased_datetime</code> or now
* <code>age → int</code> — whole years only

Both use <code>date_of_birth</code> when present, otherwise <code>year_of_birth</code> (January 1).

=== <code>save()</code> side effects ===

On every save:

# If <code>date_of_birth</code> is set and <code>year_of_birth</code> is empty → <code>year_of_birth</code> is derived
# <code>rebuild_organization_cache()</code> runs
# <code>rebuild_users_cache()</code> runs
# A second <code>save(update_fields=["organization_cache", "users_cache"])</code> persists the caches

Integrators should expect '''two write passes''' when creating or updating patients through the ORM.

== API integration notes ==

* Patient records are exposed through Care's REST API and FHIR <code>Patient</code> resources; field names in API payloads may differ from Django model names.
* Use <code>instance_identifiers</code> / <code>facility_identifiers</code> JSON for read-optimized identifier lookup; write through <code>PatientIdentifier</code> for consistency.
* <code>extensions</code> is the supported place for custom key-value data without schema migrations.
* <code>users_cache</code> and <code>organization_cache</code> are maintained by the platform — do not set them directly from clients.

{{Related}}

References/Patient - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed

Admin: OHC identity seed

Admin: OHC identity seed