CDR — User manual

One manual for CDR 1–5. All five CDR instances run the identical
software and the same storage design; they differ only in role (see
§5). This manual applies to every one of them.

A CDR (Clinical Data Repository) is the platform's authoritative store for
patient health data — the "single source of truth" for observations, no matter
how they arrived. It mirrors the shape of Cambio's real CDR, so the rest of the
platform can treat it exactly like the production record.

You don't usually use a CDR directly — services write to it and read from it.
This manual explains, in plain terms, what it does and how to tell it's
healthy.

---

1. What it's for

When a provider reports a measurement (a weight, a blood pressure, a glucose
reading, a questionnaire answer), that data is normalised by gateway.pdhc and
handed to the CDR. The CDR keeps it safely, in three increasingly useful forms,
and makes it available to dashboards and analysis tools.

gateway.pdhc ──(normalised observation)──► CDR ──► dashboards / analysis
                                             └──► Cambio CDR (real record)

---

2. How it stores data — three layers

Every observation is kept in three layers, from "exactly as received" to
"ready for a dashboard":

1. Raw — the original payload, stored verbatim and hashed, so nothing is
   ever lost and duplicates are detected.
2. Standard — the observation as a FHIR R5 resource and an
   openEHR composition. If only one format arrives, the CDR generates the
   other automatically, so both standards are always available.
3. Canonical — a clean, dashboard-friendly table of numeric health metrics
   (weight, blood pressure, heart rate, temperature, …) and activities.

This means the same reading can be read back as raw JSON, as FHIR, as openEHR,
or as a simple metric — whichever a consumer needs.

---

3. Onward delivery to Cambio

The CDR doesn't just store data — it automatically forwards concept-mapped
observations to the real Cambio CDR sandbox, so the platform's data reaches
the production clinical record. Delivery is tracked, retried on failure, and
auditable.

---

4. Checking it's healthy

Each CDR exposes a health check at /healthz returning
{status, database, service, version} — status: ok (HTTP 200) when the app
and its database are both up, degraded (HTTP 503) otherwise. This is what the
platform status page (www.pdhc.se/services.html) polls to show the green dot.

Reads and writes are authenticated (a service key per calling service), and
every read is written to an audit log so access can be traced.

---

5. The five CDRs — same software, different roles

All CDR instances are the same application with the same 39-table
schema. What differs is what each one is for:

• CDR 1 (cdr.pdhc.se) — the canonical, live repository. This is where
  gateway.pdhc forwards real provider-reported observations; it is the
  authoritative source of truth and the one that forwards to Cambio.
• CDR 2–5 (cdr2…5.pdhc.se) — analysis replicas. Identical software,
  but populated with synthetic cohorts (generated by sim.pdhc) so the
  platform's federation and analysis features can be developed and tested
  without touching real patient data. They are read-only from the analysis
  layer.

(There is also an internal CDR 6 — a deliberately lighter, loopback-only
"sim sink" with a different, simpler design; it is documented under the Sim
service, not here.)

---

6. Good to know

• Nothing is overwritten. The raw layer is immutable; corrections arrive as
  new observations, and duplicates are detected by hash.
• Both FHIR and openEHR are always available for any observation, even if
  the source only sent one of them.
• A CDR is a store, not a UI — to see the data, use the platform's
  dashboards; to understand the tables, endpoints, transformation, and
  deployment, see the technical manual (link at the top of this page, with
  a Download (Markdown) button).