plan.pdhc — User Manual

Audience: clinical and terminology authors who use the tool. No coding
knowledge assumed.

---

1. What plan.pdhc is

plan.pdhc is the authoring service for the PDHC platform. It is where you
design the clinical building blocks that every other service later uses to
collect, store, and act on patient data. Nothing here treats a patient — it is
a design workbench. Think of it as the "master library" of the platform:

• Concepts — the individual things you can measure or record (e.g. Systolic
  blood pressure, Pain level, Diagnosis). A concept says what data type is
  expected, what unit it uses, what answer options it allows, and which standard
  terminology code (LOINC, SNOMED, ICD-10, KVÅ …) it maps to.
• PlanDefinitions — a structured clinical plan built from concepts. A plan
  bundles together goals (targets/thresholds to reach), activities
  (things to do, e.g. "Measure BP"), and transactions (the specific data
  points each activity should collect).
• Questionnaires / Forms — authored forms built on top of concepts, produced
  and published as FHIR Questionnaires for data capture.
• ValueSets and Values — the reusable answer sets that coded concepts point
  at (e.g. a Severity value set of Mild / Moderate / Severe).

Everything you author is versioned and identified by a stable GUID, so
downstream services always reference exactly the concept you built.

Why it matters: a PlanDefinition's thresholds flow onward to request.pdhc,
which applies them and raises data-driven alerts. A wrong unit or a wrong
threshold authored here is a patient-safety issue, not a cosmetic one. The
tool is deliberately built with guardrails (see §6) for that reason.

---

2. The core idea: the unit lives on the concept

This is the single most important modelling rule to understand as an author.

A concept carries its own canonical unit. When you say "Systolic blood
pressure is measured in mmHg", you set that unit once, on the concept. Every
goal, threshold, activity, and transaction that refers to that concept inherits
the unit from the concept — you do not (and should not) re-type the unit on each
plan.

The plan-building forms deliberately do not offer a per-transaction unit
picker. If a stray unit does end up on a transaction or a goal target that
disagrees with the concept's own unit, the validator flags it
(W-UNIT-CONTRADICTS) so it can be corrected. Set the unit on the concept and
let everything else resolve to it — that keeps a plan automatically in sync when
terminology is later updated.

The same "resolve from the concept" principle applies to code system, concept
type, response type, and bound value set: one concept GUID resolves the whole
tree, so none of it has to be duplicated into the plan.

---

3. What you author, step by step

A typical authoring flow:

1. Create or reuse a Concept. Give it a name and display text, pick its
   response type (numeric quantity, single/multiple choice, free text …),
   set its unit if it is a quantity, and bind it to a terminology code
   (canonical_lib + canonical_refnumber, e.g. LOINC 8480-6). For coded
   concepts, attach a ValueSet of allowed answers.
2. Build a ValueSet (if needed) from reusable Values, ordered with a
   sort order, and bind it to the concept.
3. Create a PlanDefinition. Add:
   - Goals — what the plan aims for, optionally with a numeric target,
   operator, range, or a categorical target value.
   - Activities — the actions in the plan, each with optional timing
   (frequency/period/duration).
   - Transactions — the concrete data points an activity collects, each
   pointing at a concept.
4. Author a Form / Questionnaire over your concepts when you need a capture
   form, then publish it (published questionnaires become immutable).
5. Save. On save the platform runs the deterministic validators; if
   fail-closed enforcement is on, saves with blocking errors are rejected with a
   clear list of what to fix (see §6).

Concepts have a status (draft by default), so you can work up a draft before
it is relied upon.

Bulk import

Terminology authors can bulk-load concepts from a spreadsheet. An operator runs
flask import-concepts <file.xlsx|.csv> (with an optional --dry-run to
validate without committing). Rejected rows are reported with the reason, so a
large curation batch can be cleaned up before it lands.

---

4. Signing in and what you are allowed to do

Access is via the platform single sign-on (SSO). Your permissions come from your
SSO account, in three levels:

Level	Who	Can do
read_only	any signed-in user	browse concepts, plans, value sets, forms
read_write	a professional whose session includes the planning phase (or a superuser)	create/edit/delete concepts, plans, value sets, forms; use the authoring assistant
admin	a platform superuser	everything, including forcing a save past validation errors (audited)

You always see the freshest version of your permissions: the tool re-checks your
session with SSO on every request, so if your access is changed or revoked
centrally it takes effect immediately — there is no stale cached copy of your
rights.

If SSO asks you to change your password, the tool sends you to the SSO
change-password page before letting you continue.

---

5. The FHIR R5 terminology service (for the people who consume your work)

Everything you author is also published, live, as a standards-based FHIR R5
terminology service at /api/v1/. You do not have to operate this — it is how
other systems read the library you build — but it is useful to know it exists:

• ValueSet $expand — hand a system your value set and it returns the full
  list of allowed answers.
• ValueSet $validate-code — check whether a given code is a legal answer in
  one of your value sets.
• CodeSystem $lookup — look up one of your local concepts and get its
  display text and terminology binding back. (Locally, a concept's code is its
  GUID.)
• ConceptMap $translate — translate between your local concept and its
  external standard code (LOINC/SNOMED/…).

The practical benefit for you: the moment you curate a concept or a value set,
downstream services see the change through these operations — you are the single
source of truth for platform terminology.

---

6. The authoring assistant and the guardrails (opt-in)

plan.pdhc includes an opt-in guided-authoring assistant designed so that
someone who is not a terminology specialist can still build a correct plan. It
is two distinct layers:

Layer 1 — the deterministic checker (always the floor)

A fixed set of rules, identical for every author and every path, that catches the
mistakes a novice makes. Examples of what it flags:

• a quantity concept with no unit (E-UNIT-REQUIRED)
• a single/multiple-choice concept with no answer set (E-VALUESET-REQUIRED)
• an unknown response type name (E-RESPONSE-TYPE-UNKNOWN)
• a dangling reference — a goal/transaction pointing at a concept that
  doesn't exist (E-DANGLING-REF)
• an inverted range where low > high (E-RANGE-INVERTED)
• warnings for a missing or unverified terminology code, a unit that
  contradicts the concept's unit, or an empty plan

Each issue comes back with a plain-language message telling you what is wrong.
When fail-closed enforcement is switched on, an error-level issue blocks the
save; warnings always inform but never block. (An admin can force a save past
errors, and that override is written to the audit log.)

Layer 2 — the Claude-assisted co-author (the helper)

When enabled and configured, you can describe what you want in plain language
("resting systolic blood pressure, adult") and the assistant proposes a complete,
correct concept: the right response type, unit, terminology code, and any answer
set — and it searches for an existing concept first so you don't re-create
one that already exists. It then runs the Layer-1 checker on its own proposal and
shows you the result, so it can never quietly hand you something invalid.

Important properties:

• The assistant only proposes — it pre-fills the form for you to review and
  confirm. It never saves on its own.
• It is off by default and must be switched on by an operator. When off, the
  assistant endpoints simply report "disabled" and nothing about normal
  authoring changes.
• No patient data is ever involved — only concept/terminology metadata and your
  typed intent.
• The operator can pick which Claude model backs it (a cheaper one for quick
  checks, a stronger one for the hardest terminology calls). Without a key, the
  tool still runs Layer 1 (validation-only) and never breaks.

There is also a "Check openEHR export" helper that asks rosetta.pdhc whether your
concept set can be exported to openEHR, degrading quietly if that service isn't
configured.

---

7. Quick reference

• Where: https://plan.pdhc.se
• Sign-in: platform SSO; your role (read-only / read-write / admin) comes
  from your SSO account and the planning phase.
• What you build: Concepts → ValueSets/Values → PlanDefinitions (goals +
  activities + transactions) → Questionnaires/Forms.
• Golden rule: set the unit on the concept; everything else resolves to
  it.
• Safety: the deterministic validator is the floor; the assistant is the
  helper. The assistant proposes, you dispose.

For the API surface, deployment, and configuration, see technical.md.