# cgm.pdhc — User manual

cgm.pdhc is the **CGM (continuous glucose monitor) provider portal** for the
PDHC platform — the "provider side" for glucose-monitoring devices (Abbott
FreeStyle and similar). When the platform needs a patient's glucose monitored
over a period, it sends this service an order; the provider acknowledges it,
collects glucose readings across the monitoring window, and streams them back
into the platform.

Live at **https://cgm.pdhc.se**. It has two faces: a **web portal** for human
operators, and a **REST API** for device/system integration.

---

## 1. What it does, in plain terms

```
request.pdhc ──(monitoring order)──►  cgm.pdhc  ──(glucose readings, in batches)──►  gateway.pdhc ──► platform dashboards
```

1. **An order arrives.** `request.pdhc` pushes a monitoring order — a patient
   who needs continuous glucose monitoring over a window (e.g. 14 days).
2. **The provider acknowledges it** and monitoring begins.
3. **Readings are collected and submitted in batches** for the whole window.
4. **Each batch is forwarded to `gateway.pdhc`**, which validates, enriches,
   and stores it so it shows up on the platform's dashboards.
5. **When the window ends, a "completed" status is sent.**

Each deployment is **one provider** (its identity is fixed in configuration).

### Built-in glucose simulator (out of the box)

This instance ships with a **glucose simulator**. The moment you acknowledge
an order, it **automatically starts generating one realistic reading per
minute** (a gentle random walk around 5.5 mmol/L, clamped to a safe range) and
submitting it, until you complete monitoring. So readings flow **without a
real device** — handy for demos and testing. An operator can also push real
readings via the API instead.

---

## 2. Using the web portal

Log in at `https://cgm.pdhc.se/login` (username + key; the first admin is
bootstrapped at deploy). The portal gives you:

- **Dashboard** (`/`) — tasks by state (dispatched / monitoring / completed),
  receipts, active glucose streams, and sync status at a glance.
- **Tasks** (`/tasks`) — incoming monitoring orders; open one to see its audit
  trail, the original request, live stream status, and the batch log.
  - **Acknowledge** — the key action: starts monitoring (and the simulated
    stream). Flash: *"Task acknowledged — glucose stream started."*
  - **Complete monitoring** — stops the stream and sends the final status.
- **Receipts / Gateway receipts** — proof each batch was accepted downstream.
- **Audit** — full operation log.
- **Docs** — the technical guide (downloadable).
- **Users** (admin) and **Trigger sync**.

**Task lifecycle:** `dispatched → acknowledged → monitoring → completed`.

---

## 3. Using the API (integrators)

All API calls use the `X-API-Key` header (keys are scoped `read` / `write`).
Base path `/api/v1`. The essentials:

| Do this | Call |
|---|---|
| Check health (no auth) | `GET /api/v1/health` → `{status, database, service}` |
| List my tasks | `GET /api/v1/provider-tasks/my` |
| Acknowledge / start monitoring | `POST /api/v1/provider-tasks/<token>/accept` |
| **Submit a batch of readings** | `POST /api/v1/provider-tasks/<token>/observe` |
| End monitoring | `POST /api/v1/provider-tasks/<token>/observe/complete` |
| Stream status / batch log | `GET …/observe/status`, `GET …/observe/log` |

A reading batch looks like this — send `transaction_guid`, `value`,
`recorded_at`; **do not** send the concept or unit, the gateway derives those
from the care plan:

```
POST /api/v1/provider-tasks/<token>/observe
X-API-Key: <write-key>
{ "observations": [
    { "transaction_guid": "tx-glucose-001", "value": 5.6,
      "recorded_at": "2026-04-01T08:00:00Z" } ] }
```

Manage keys with `POST /api/v1/api-keys` (and `/revoke`, `/rotate`). A new
key's raw value is shown **once** — store it securely.

---

## 4. Access & onboarding

- **Human operators** log into the portal with a username + key.
- **API clients** use `X-API-Key` (create/rotate/revoke via the API).
- **Registering the provider instance itself** (its identity, provider access
  token, and push secret) is done by PDHC operations via the provider wire-up
  tooling — not something the day-to-day operator does.

---

## 5. Good to know

- The **only actions that matter operationally** are *Acknowledge* (start) and
  *Complete* (stop) — everything in between is automatic (simulator) or
  pushed by your device integration.
- Glucose readings carry a `transaction_guid` linking each one to the care
  plan; the platform derives the glucose concept and unit (mmol/L) from that
  context, so you never send them.
- Every batch is acknowledged by the gateway with a **receipt** — check the
  Receipts page (or `GET /api/v1/provider-receipts`) if you need proof.
- For endpoints, the ingest/forward chain, config, and deployment, see the
  **technical manual** (link at the top of this page — with a **Download
  (Markdown)** button).