| name | care-reference-doc |
| description | Use when creating or updating a REFERENCE doc (the "How is it built?" technical layer) for a Care EMR model/resource in the Care docs site. Trigger whenever a Care backend model, Pydantic resource spec, field, enum, choice, validation, or API schema changes — especially after merging a Care PR — or when adding a reference page for a new model. Use it even if the user just says "the docs are out of date", "update the reference for X", "a field changed in Care", or pastes a Care diff/PR. Covers reading the Django model + resource specs as the source of truth, the exact page structure, link/MDX conventions, 3.0≡3.1 versioning, and build validation. |
Building Care reference docs
A reference answers "How is it built?" for developers and integrators: the models, fields, types, relationships, enums, JSON-field shapes, API schemas, and save/serialization behaviour of one Care EMR module.
References live at versioned_docs/version-3.0/references/<domain>/<slug>.mdx (mirrored to version-3.1). One reference page documents one backend model file and its resource specs.
The two-layer rule (this is the whole point)
A Care resource has two layers, and a reference must cover both:
- Storage layer — the Django model in the Care backend (
care/emr/models/<resource>.py). Many fields are opaque JSONFields (period, hospitalization, care_team, …) whose real structure is not visible here.
- API / implementation layer — the Pydantic resource specs in
care/emr/resources/<resource>/ (built on EMRResource in care/emr/resources/base.py). These define the enums, validation, the structured shape of those JSON fields (via nested specs), and the read/write schemas (<X>CreateSpec / <X>UpdateSpec / <X>ListSpec / <X>RetrieveSpec). Enums/choices live in spec.py, constants.py, or valueset.py; shared types are in care/emr/resources/common/ (CodeableConcept, Coding, Period, Quantity, …).
A reference that only reads the Django model is wrong — it will miss enums, JSON-field structure, validation, and the request/response schemas integrators actually need.
Source of truth
The local Care backend checkout (a sibling of the docs repo — typically ../care or code/care). Read the real code; never infer fields from memory. If the user names a specific checkout or commit, use exactly that.
Workflow
Creating a new reference
- Read the gold examples in this repo to internalize structure, depth, and tone — do this every time, they are the living template:
versioned_docs/version-3.0/references/clinical/patient.mdxversioned_docs/version-3.0/references/clinical/encounter.mdx (enums + nested JSON shapes)versioned_docs/version-3.0/references/facility/organization.mdx (tree model + multiple related models + specs)
- Read the backend source IN FULL: the model file (every class in it) and every
.py in the matching care/emr/resources/<resource>/ dir (skip __init__.py), plus referenced shared types in resources/base.py / resources/common/.
- Write the page following the structure below to
versioned_docs/version-3.0/references/<domain>/<slug>.mdx.
- Mirror & validate (see those sections).
Updating for a Care change / PR
This is the common case. Goal: keep the reference faithful to the merged code.
- Get the diff — e.g. in the Care checkout
git show <sha>, git diff <base>..<head>, or read the PR. Identify which models / resource specs changed.
- Map each changed backend file to its reference page. The mapping is
care/emr/models/<x>.py → references/<domain>/<x-slug>.mdx. If unsure, grep the docs for the model name or the GitHub source link.
- Re-read the changed model + specs, then update the affected sections only — field tables, enum tables, nested-shape blocks, the resource-specs table, save behaviour. Preserve the rest.
- Mirror to 3.1, build, and report exactly what changed and why.
If a change adds a whole new model with no page yet, create one. If it deletes a model, remove the page and any links to it (grep first).
Page structure
Match the gold examples. In order:
- Frontmatter:
sidebar_position: <n> (ordering within the domain; the sidebar is autogenerated).
# <Title> then a one-line intro: Technical reference for the module in Care EMR. (link to the concept only if one exists).- A
**Source:** block linking the model file and each spec file on GitHub (https://github.com/ohcnetwork/care/blob/develop/<repo-relative-path>).
- A short paragraph naming the two layers (storage vs specs) when the model has opaque JSON fields.
## Models — a markdown table of every Django class in the file with a one-line purpose. State the base class each extends (EMRBaseModel gives external_id, audit fields, soft-delete via deleted, history/meta; SlugBaseModel adds facility-scoped slugs). Link the base to ../foundation/base-model.mdx.## <MainModel> fields — field tables grouped under ### subheadings when there are many. Use the real Django field names and types; where a spec constrains/shapes a field, add columns or notes for the spec type, required/optional, default, and validation. Replace bare JSONField notes with the actual nested shape.- Enum tables — a
### <EnumName> values table listing the real values from constants.py/valueset.py/spec.py.
- Nested JSON shapes — a
text-fenced block for each JSON field's structure (e.g. period → PeriodSpec { start, end }).
## Related models — secondary classes (FK relationships shown as a small text block).## Resource specs (API schema) — a table mapping the Pydantic specs to their role: <X>CreateSpec (write · create), <X>UpdateSpec (write · update), <X>ListSpec (read · list), <X>RetrieveSpec (read · detail), plus nested specs. Note validation and server-maintained behaviour (e.g. "status changes append to status_history server-side"), and bound value sets.## Methods & save behaviour — only if the model overrides / or has notable methods; describe side effects, cache rebuilds, validators, signals.
Keep it dense and faithful: tables and code over prose, no marketing, no invented fields. Document every model class, enum, and JSON shape present in the source.
Conventions (shared with concept docs)
Read references/conventions.md for the full detail on:
- Domains & slugs — the 10 reference domains and how to pick one.
- Links —
.mdx for normal internal links; extensionless only for the translated docs (patient, create-patient). Getting this wrong breaks the Malayalam build.
- MDX safety — no
{#custom-anchor} heading ids; wrap literal { } in backticks/fences; never write tool-call XML into a file.
- Versioning — author in
version-3.0, then mirror byte-identical to version-3.1.
- Build validation —
npm run build (all locales) is the authoritative gate.
Always read that file before writing, then return here.
Language
Write prose in ASD-STE100 Simplified Technical English — read ../care-concept-doc/references/ste.md. Active voice, present tense, ≤25 words per sentence, one term for one thing, no marketing language and no hedging.
This applies to the page intro, section intros, admonitions, and any explanatory paragraph. It does not apply to the field, enum, and spec tables: terse noun-phrase cells are correct there, and STE itself prefers a table to prose for structured data. Keep the type notation (CharField(100), nullable) exactly as the code has it.
