dashboard.pdhc — User Manual

1. Logging in

• Development: AUTH_MODE=off — you are logged in automatically as a dev
  super-user. No credentials required.
• Production: AUTH_MODE=sso — log in via the PDHC SSO portal; the
  dashboard trusts the X-PDHC-User header set by the SSO reverse proxy.
• Admin users see all organisations. Regular users see only patients from
  organisations they are a member of (Rule 24).

2. Landing page — Eligible patients

After login you land on /:
- Patient list — one row per patient in your organisation with at least
one observation. Columns: Patient GUID (clickable), total observation
count, count per concept (names only), date of the latest observation
overall.
- Concept picker — check up to two concept boxes and click
"Show curves (max 2)" to overlay time-activity curves for the cohort.
- Refresh from gateway (top-right button) — pulls the latest observations
from gateway.pdhc for your organisations. This is the single canonical way
to update the data; there is no background polling.

3. Patient dashboard

Click a patient GUID on the landing page to open /patient/<guid>:
- Latest values table — one row per concept with the most recent value,
unit, and timestamp.
- Time-activity chart — every concept the patient has data for is shown
as its own line on the chart.
- Back link returns to the landing page.

4. Refreshing data

The Refresh from gateway button is visible on every page. Clicking it:
1. Clears the local observation cache for each organisation you belong to.
2. Pulls the current Observation bundle from gateway.pdhc.
3. Repopulates the cache and writes an entry to the refresh log.

If the refresh fails, the error is stored in the refresh log and the existing
cache remains untouched.

5. Reading the charts

• X axis: time (day-grouped).
• Y axis: numeric value of the observation.
• On the landing cohort chart, each point is one observation for one patient
  in the cohort; hover to see value and patient GUID.
• On the patient chart, each line is one concept; use the legend to toggle.

6. API for downstream tools

The dashboard exposes its curve data as FHIR R5 so it can be re-consumed
elsewhere:
- GET /api/v1/series?patient=<guid>&concept=<guid> — returns a FHIR Bundle
of Observation resources.
- GET /metadata — CapabilityStatement describing all endpoints.

7. Getting help

• Runtime logs: results/<timestamp>_results/app.log
• Technical details: docs/technical.md
• Deployment plan + progress: readme.md, progress.md