# Architecture — request.pdhc

Audience: integrators, infra reviewers, anyone tracing a request end-to-end.

## 1) What this service is

**request.pdhc** is the ServiceRequest + care-plan orchestration layer of the
PDHC platform. It turns a clinician's intent — "collect these measurements for
this patient under this contract" — into a durable, auditable
`ServiceRequest`, matches it to providers, and brokers the credentials a
provider needs to report back. It owns:

- The `ServiceRequest` lifecycle. An SR is a **PlanDefinition snapshot for a
  patient**: it captures the patient excerpt, the edited PlanDefinition (and
  optionally the CarePlan) at create time so later template edits never
  silently mutate an issued request.
- `CarePlan` — the patient-specific instance of a PlanDefinition (since #310).
- Provider matching + delivery: `ServiceRequestContractMatch`,
  `ServiceRequestReceipt`, and the outbound webhook subsystem.
- `ProviderAccessToken` (PAT) issuance and the `DataExchangeGrant` HMAC-signed
  composite key that lets a specific provider report on a specific SR.
- `DispatchRequest` — forwarding a PlanDefinition to a provider via plan.pdhc.
- The audit trail (`AuditLog`) for every state-changing action **and** every
  patient-identified read.

It does **not** own:

- **Identity** (sso.pdhc).
- **The patient registry** — patients live in **ips.pdhc**. request.pdhc holds
  **no `Patient` table**; it *proxies* IPS via `patient_service.py`
  (`IPS_BASE_URL`) and stores only a JSON `patient_excerpt` snapshot on the SR.
- **Contract terms** (contract.pdhc).
- **PlanDefinition / CarePlan templates authoring** (plan.pdhc — request.pdhc
  snapshots them).
- **Inbound observation routing** (gateway.pdhc).
- **Terminology / canonical URIs** (termbank.pdhc).

## 2) Container topology

Three containers in the `request` compose project (`docker-compose.yml`):

```
                                                                
  Browser ──HTTPS──▶ nginx (miserver) ──▶ request_pdhc_app:9060 ──▶ request_pdhc_db:9061
                              │                       │
                              │                       ├─▶ ips.pdhc        (patient proxy + consent)
                              │                       ├─▶ plan.pdhc:9030  (PlanDefinition dispatch)
                              │                       ├─▶ contract.pdhc:9021 (status check)
                              │                       └─▶ sso.pdhc:9000   (token validation)
                              │
  request_pdhc_worker ──▶ outbound webhooks ──▶ provider webhook URLs (1177.pdhc, cgm.pdhc, ...)
   (flask webhook run-worker)
```

- **`request_pdhc_app`** — Flask + gunicorn (2 workers, port 9060). Runs
  `flask db upgrade` on start via `entrypoint.sh`. Loopback-bound
  `127.0.0.1:9060`.
- **`request_pdhc_db`** — PostgreSQL 16-alpine. DB user `request_admin`,
  database `request_pdhc`. Loopback-bound `127.0.0.1:9061 → 5432`. Named
  external volume `request_pdhc_pgdata`.
- **`request_pdhc_worker`** — same image/env as the app, but its entrypoint is
  overridden to `flask webhook run-worker --interval 5`. It runs **no
  migrations and binds no port**; it just ticks the outbound
  `WebhookDelivery` queue (backoff + dead-letter, see §5.4). `restart:
  unless-stopped`, depends on both `db` (healthy) and `app` (healthy).

All cross-service HTTP uses the `*_BASE_URL` config values
(`IPS_BASE_URL`, `PLAN_BASE_URL`, `CONTRACT_BASE_URL`, `SSO_BASE_URL`); on the
macmini these resolve through nginx / `host.docker.internal`.

## 3) Data flow — happy path

```
Requester            request.pdhc          plan/contract/ips        provider           gateway.pdhc
─────────           ─────────────         ─────────────────       ──────────         ──────────────
POST /ServiceRequest
  body: patient_guid,
  plan_definition_guid,
  contract_guid ─────▶
                     fetch patient excerpt (ips)
                     snapshot PlanDefinition (plan)
                     validate contract (contract)
                     persist SR (+ forms)
                     match to providers ──────────────────────────────────────────────────────────
                     enqueue webhook  ─── worker ──────────────▶ POST provider webhook URL
                                                                  (metadata only + download_url)
                     mint DataExchangeGrant
   ◀── 201 ──────────
                                          provider pulls bundle ◀─ GET /provider/download/<sr>
                                                                  (issues/returns grant_token)
                                                                  ... fulfils ...
                                                                POST report ─────────▶ /api/v1/provider/report/<sr>
                                                                  X-Provider-Token + grant
                                                                                      validate PAT ─┐
                                                                                      validate grant│
                                                                        ◀─ /api/v1/internal/grant/validate
                                                                                      enrich + persist obs
```

Note the deliberate split: **observation data** is POSTed to
**gateway.pdhc** `/api/v1/provider/report/<sr>` (which writes inbound
observations after full validation). request.pdhc's own
`/api/v1/provider/status/<sr>` (and its deprecated `/provider/report/<sr>`
alias) record only **SR lifecycle state** on the contract-match — a payload
sent there never reaches inbound observations (see `provider.py`).

## 4) Data model

13 tables. Cross-service references are stored as **GUID strings**, never
enforced FKs — the owning service (sso / ips / plan / contract) is the source
of truth (Rule 18). Verified against the model files under `app/models/`.

### 4.1 There is no Patient table

Patients live in **ips.pdhc**. `app/services/patient_service.py` proxies
`GET/POST/PUT/DELETE {IPS_BASE_URL}/fhir/Patient[...]` and
`{IPS_BASE_URL}/api/v1/patients/<guid>/clinics` (need-to-know check). The only
patient data at rest here is the JSON `patient_excerpt` captured onto a
`ServiceRequest` at create time.

### 4.2 ServiceRequest (`service_requests`)

FHIR R5 ServiceRequest — a patient excerpt + an edited **PlanDefinition
snapshot**.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `status` | str(30) | default `draft` |
| `intent` | str(20) | default `order` |
| `priority` | str(20) | default `routine` |
| `patient_guid` | UUID v4 | indexed; references ips.pdhc |
| `patient_excerpt` | JSON | snapshot pulled from IPS at create |
| `plan_definition_guid` | UUID v4 | references plan.pdhc |
| `plan_definition_snapshot` | JSON | frozen template — later edits don't leak in |
| `care_plan_guid` | UUID v4, nullable | since #310; NULL for legacy/direct SRs |
| `fhir_resource` | JSON | assembled FHIR R5 ServiceRequest |
| `contract_guid` | UUID v4, nullable | indexed |
| `requester_user_guid` | UUID v4 | required |
| `requester_user_name` | str(255), nullable | |
| `requester_org_guid` | UUID v4, nullable | indexed (canonical alias `requesting_org_guid` in `to_dict`, #294) |
| `requester_org_name` | str(255), nullable | (alias `requesting_org_name`) |
| `notes` | text | |
| `period_start`, `period_end` | datetime, nullable | validity period |
| `created_at`, `updated_at` | datetime | |

Relationships: `contract_matches` → `ServiceRequestContractMatch`; `forms` →
`ServiceRequestForm` (ordered by `sort_order`).

### 4.3 ServiceRequestForm (`service_request_forms`)

Links an SR to one or more forms from the Plan catalogue. Unique on
`(service_request_guid, form_guid)`.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `service_request_guid` | UUID v4 | FK → `service_requests.guid` |
| `form_guid` | UUID v4 | references plan.pdhc form |
| `form_version` | str(50), nullable | |
| `form_snapshot`, `render_ready_snapshot` | JSON | |
| `display_title` | str(255), nullable | |
| `sort_order` | int | default 0 |
| `created_at`, `updated_at` | datetime | |

### 4.4 ServiceRequestContractMatch (`service_request_contract_matches`)

Links an SR to a matching contract/provider.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `service_request_guid` | UUID v4 | FK → `service_requests.guid` |
| `contract_guid` | UUID v4 | |
| `provider_org_guid` | UUID v4 | indexed |
| `provider_name` | str(255), nullable | |
| `match_type` | str(20) | `offer` \| `push`, default `offer` |
| `status` | str(30) | default `pending` |
| `sent_at`, `response_at` | datetime, nullable | |
| `response_payload` | JSON | |
| `created_at`, `updated_at` | datetime | |

Relationship: `receipts` → `ServiceRequestReceipt`.

### 4.5 ServiceRequestReceipt (`service_request_receipts`)

Delivery receipt for a pushed SR.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `service_request_guid` | UUID v4 | FK → `service_requests.guid` |
| `contract_match_guid` | UUID v4 | FK → `service_request_contract_matches.guid` |
| `receipt_token` | str(255) | unique |
| `delivery_method` | str(20) | default `push` |
| `delivery_status` | str(30) | default `pending` |
| `delivery_payload`, `response_payload` | JSON | |
| `response_received` | bool | default `false` |
| `created_at` | datetime | |

### 4.6 CarePlan (`care_plans`)

FHIR R5 CarePlan — the patient-specific instance of a PlanDefinition (since
#310). Observations reference a CarePlan via `basedOn[]`; the chain
`Observation → CarePlan → PlanDefinition → Transaction → Concept` is the
canonical provenance.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | (canonical alias `care_plan_guid` in `to_dict`) |
| `patient_guid` | UUID v4 | indexed |
| `plan_definition_guid` | UUID v4 | indexed |
| `status` | str(20) | FHIR CarePlan.status, default `draft` |
| `intent` | str(20) | FHIR CarePlan.intent, default `plan` |
| `title`, `description` | str/text, nullable | |
| `period_start`, `period_end` | timestamptz, nullable | |
| `plan_definition_snapshot` | JSON | frozen template at create |
| `goals` | JSON | list of `{concept_guid, target_value, target_comparator, description}` |
| `care_team_user_guids` | JSON | list of user guids |
| `created_by_user_guid` | UUID v4, nullable | |
| `created_at`, `updated_at` | timestamptz | |

### 4.7 DispatchRequest (`dispatch_requests`)

A request to forward a PlanDefinition to a provider via plan.pdhc.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `plan_definition_guid` | UUID v4 | renamed from `careplan_guid` in #318; `to_dict` still emits the legacy alias |
| `provider_guid` | UUID v4 | indexed |
| `assigned_user_guid` | UUID v4, nullable | |
| `dispatch_notes` | text | |
| `status` | str(20) | `pending` → `submitted` \| `failed` |
| `idempotency_key` | str(255) | unique — replays return the existing receipt |
| `provider_status` | str(50), nullable | provider-reported status |
| `provider_status_updated_at` | datetime, nullable | |
| `created_at`, `updated_at` | datetime | |

Relationship: `receipts` → `DispatchReceipt`.

### 4.8 DispatchReceipt (`dispatch_receipts`)

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `dispatch_request_guid` | UUID v4 | FK → `dispatch_requests.guid` |
| `receipt_token` | str(255) | unique |
| `status` | str(20) | `accepted` \| `error`, default `accepted` |
| `response_payload` | JSON | upstream body |
| `created_at` | datetime | |

### 4.9 ProviderAccessToken — PAT (`provider_access_tokens`)

Binds a **bcrypt-hashed** API token to a provider org + contract. Three-state
lifecycle (#136): `active` / `deprecated` / `revoked`, with a rotation grace
window (`PAT_DEPRECATED_GRACE_DAYS`, default 14) during which a deprecated
token is still accepted.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `token_hash` | str(255) | bcrypt (12 rounds); raw token shown once at issue |
| `provider_org_guid` | UUID v4 | indexed |
| `contract_guid` | UUID v4 | indexed |
| `scopes` | str(255) | comma list, default `read` |
| `delivery_mode` | str(20) | `push` \| `poll`, default `poll` |
| `push_endpoint_url` | str(512), nullable | provider's inbound URL |
| `push_auth_key_encrypted` | str(512), nullable | Fernet-encrypted (#151) |
| `expires_at` | datetime | |
| `revoked` | bool | legacy flag, still honoured |
| `revoked_at` | datetime, nullable | |
| `status` | str(20) | `active`/`deprecated`/`revoked`, indexed |
| `deprecated_at` | datetime, nullable | grace clock start |
| `rotated_to_guid` | UUID v4, nullable | successor PAT |
| `created_by_user_guid` | UUID v4 | |
| `created_at` | datetime | |

### 4.10 DataExchangeGrant (`data_exchange_grants`)

HMAC-signed composite key authorizing data exchange for **one**
ServiceRequest. The HMAC secret (`HMAC_SECRET`) is held **only** by
request.pdhc; gateway.pdhc never sees it and delegates validation to
`/api/v1/internal/grant/validate`.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `service_request_guid` | UUID v4 | FK → `service_requests.guid` |
| `patient_guid` | UUID v4 | indexed |
| `provider_org_guid` | UUID v4 | indexed |
| `contract_guid` | UUID v4 | |
| `grant_token` | str(128) | HMAC token |
| `grant_type` | str(20) | `download` \| `upload` \| `bidirectional` (default `bidirectional`) |
| `expires_at` | datetime | |
| `used_count` | int | default 0 (incremented on each use) |
| `max_uses` | int, nullable | **NULL = unlimited** |
| `revoked` | bool | |
| `created_at` | datetime | |

`is_valid()` fails on revoked, expired, or `max_uses` reached. The internal
validate endpoint derives `uses_remaining = max_uses - used_count` (or `null`
when unlimited) for the caller's convenience.

### 4.11 WebhookSigningSecret (`webhook_signing_secrets`)

Per-provider-org HMAC key for signing outbound webhook bodies (#136). Secret
is **Fernet-encrypted** (`WEBHOOK_SECRETS_KEY`) at rest. Same three-state
lifecycle as PATs: **only `active` signs new bodies**; `active` +
grace-period `deprecated` are accepted for verification.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `provider_org_guid` | UUID v4 | indexed |
| `secret_encrypted` | text | Fernet ciphertext |
| `status` | str(20) | `active`/`deprecated`/`revoked`, indexed |
| `issued_at`, `deprecated_at`, `revoked_at` | datetime | |
| `rotated_to_guid` | UUID v4, nullable | |
| `created_by_user_guid` | UUID v4 | |

### 4.12 WebhookDelivery (`webhook_deliveries`)

One scheduled outbound webhook (#140). Payload is **metadata only, never
PHI** — the body carries a `download_url`, and the provider pulls the FHIR
Bundle from the authenticated download endpoint. Lifecycle: `pending →
in_flight → (succeeded | dead_letter)`.

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `event_id` | UUID v4 | unique; sent as `X-PDHC-Event-Id` |
| `event_type` | str(64) | e.g. `service_request.dispatched` |
| `provider_org_guid` | UUID v4 | indexed |
| `service_request_guid` | UUID v4, nullable | indexed |
| `webhook_url` | str(1024) | provider endpoint |
| `payload_json` | text | exact signed body |
| `signature` | str(128), nullable | `sha256=<hex>`, sent as `X-PDHC-Signature` |
| `signing_secret_guid` | UUID v4, nullable | which secret signed it |
| `attempt_count` | int | |
| `next_attempt_at` | datetime | indexed; drives the due query |
| `status` | str(20) | `pending`/`in_flight`/`succeeded`/`dead_letter`, indexed |
| `last_response_code` | int, nullable | |
| `last_response_body_excerpt` | str(1024), nullable | |
| `last_error` | str(512), nullable | |
| `last_attempt_at`, `succeeded_at` | datetime, nullable | |
| `created_at` | datetime | |

### 4.13 AuditLog (`audit_logs`)

Append-only. Written for every state-changing action **and** every
patient-identified read (see §4.13.1).

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `correlation_id` | str(255), nullable | request/session correlation |
| `user_guid` | UUID v4, nullable | actor |
| `action` | str(100) | e.g. `service_request.create.requested`, `feed.accessed` |
| `resource_type` | str(50), nullable | e.g. `ServiceRequest`, `WebhookDelivery` |
| `resource_guid` | UUID v4, nullable | |
| `details` | JSON | free-form context |
| `ip_address` | str(45), nullable | |
| `data_subject_guid` | UUID v4, nullable | indexed — the patient the row is about |
| `created_at` | datetime | |

#### 4.13.1 Read-side audit inventory (ticket #227, PDL Ch 4 §3)

Every GET endpoint that returns patient-identified data writes one `AuditLog`
row on success (HTTP 2xx). Failed reads (4xx / 5xx) skip the row — the
underlying access didn't happen. Wired via the `@audit_read(...)` decorator
from `app.services.audit_service` (or inline `log_event` for a few
pre-#227 routes).

| Method | URL rule (`/api/v1` prefix) | `action` | `resource_type` |
|---|---|---|---|
| GET | `/Patient` | `patient.list` | `Patient` |
| GET | `/Patient/<guid>` | `patient.read` | `Patient` |
| GET | `/CarePlan` | `careplan.list` | `CarePlan` |
| GET | `/CarePlan/<guid>` | `careplan.view` | `CarePlan` |
| GET | `/ServiceRequest` | `service_request.list` | `ServiceRequest` |
| GET | `/ServiceRequest/<guid>` | `service_request.read` | `ServiceRequest` |
| GET | `/ServiceRequest/<guid>/matches` | `service_request.matches.list` | `ServiceRequest` |
| GET | `/ServiceRequest/<guid>/receipts` | `service_request.receipts.list` | `ServiceRequest` |
| GET | `/ServiceRequest/<guid>/forms` | `service_request.forms.list` | `ServiceRequest` |
| GET | `/ServiceRequest/receipt/<token>` | `service_request.receipt.read` | `ServiceRequestReceipt` |
| GET | `/requests` | `request.list` | `ServiceRequest` |
| GET | `/requests/<guid>` | `request.read` | `ServiceRequest` |
| GET | `/provider/feed` | `feed.accessed` | (metadata only) |

Catalogue / metadata reads that carry no patient identifiers (`/Form`,
`/PlanDefinition`, `/Contract`, `/providers`, `/metadata`,
`/admin/provider-tokens`, `/docs/*`, `/api`) are intentionally out of scope.
Authoring routes (POST/PUT/DELETE) write their own inline `log_event` rows.

When adding a new GET that returns patient-identified data, decorate it with
`@audit_read('<action>', resource_type='<Type>', guid_arg='<view_arg>')`. The
decorator writes one row on 2xx, none on 4xx/5xx, and swallows internal
failures so a flaky audit table can't break the response.

### 4.14 LocalUser (`local_users`)

Minimal Flask-Login session state. Real auth is SSO; this stores
`sso_user_guid`, `email`, `display_name`, `role` (default `read_only`),
`is_active`, the cached `access_blob`, and `last_login`. Not a source of
identity truth.

## 5) Security

### 5.1 Auth surfaces

- **Public surface**: SSO Bearer JWT, validated on **every** request against
  sso.pdhc — the access blob is **never cached** client-side, so an SSO-side
  logout takes effect immediately. `AUTH_DISABLED=true` is honoured **only**
  when `FLASK_ENV=development` (config.py refuses to start otherwise, #91).
- **Internal surface**: `X-Service-Key` (`INTERNAL_SERVICE_KEY`), validated by
  `@requires_service_key`. Blueprint: `app/api/internal.py`, mounted under
  `/api/v1`.
- **Provider surface**: `X-Provider-Token` (PAT), validated by
  `@requires_provider_token`. Provider org identity is derived from the token,
  **never** from request params.

### 5.2 Provider endpoints (`app/api/provider.py`, `/api/v1` prefix)

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/provider/feed` | PAT `read` | List SRs for this provider — **metadata only** (data minimisation); audited `feed.accessed`. |
| GET | `/provider/download/<sr_guid>` | PAT `read` | Download the full FHIR Bundle; issues a `DataExchangeGrant` if none exists and returns `grant_token`. |
| POST | `/provider/status/<sr_guid>` | PAT `write` | Canonical **lifecycle status** update; requires the composite key (`patient_guid`, `contract_guid`, `provider_org_guid`, `grant_token`). Body org must match the PAT. |
| POST | `/provider/report/<sr_guid>` | PAT `write` | **DEPRECATED alias** of `/status`. Logs `report.deprecated_alias_used`. Observation *data* goes to **gateway.pdhc** `/provider/report`, not here. |
| POST | `/provider/validate-token` | none (token is the credential) | Called by gateway.pdhc to resolve a raw PAT → org/contract/scopes/delivery-mode + decrypted push key. |
| POST | `/provider/receipt/<receipt_token>/ack` | PAT `write` | Acknowledge a push-delivery receipt. |

### 5.3 Internal endpoints (`app/api/internal.py`, `X-Service-Key`)

- `GET /api/v1/internal/service-request/<sr_guid>/context` — pre-extracted SR
  context for gateway observation reconstruction (transaction→concept, patient
  cross-check).
- `POST /api/v1/internal/grant/validate` — validate a `DataExchangeGrant`
  token. Returns `contract_guid`, `grant_type`, `uses_remaining`; distinguishes
  `GRANT_EXPIRED` from `GRANT_TOKEN_INVALID`. **This is how the HMAC secret
  stays inside request.pdhc.**
- `POST /api/v1/internal/auto-provision-pat` — called by contract.pdhc on
  contract create/update; fetches push-config from SSO and issues a PAT if none
  exists (poll vs push decided by whether SSO returned a push endpoint).

### 5.4 Outbound webhook subsystem (`request_pdhc_worker`)

`app/services/webhook_dispatcher.py` + the `flask webhook` CLI group
(`app/__init__.py`). The worker container runs `flask webhook run-worker
--interval 5`, which calls `tick()` on a loop:

1. `enqueue(...)` writes a `WebhookDelivery`. The body is signed with the
   org's **active** `WebhookSigningSecret` (`X-PDHC-Signature: sha256=<hex>`).
   No active secret → the row goes **straight to `dead_letter`** and a ticket
   is filed (never silently retried).
2. `tick()` picks up `pending` rows whose `next_attempt_at <= now` and POSTs
   them. Non-2xx / transport error → `attempt_count++` and reschedule per
   `BACKOFF_SECONDS = [5, 25, 120, 600, 3600]` (6 attempts total).
3. After the last attempt the row becomes `dead_letter` and a **high-priority
   ops ticket** is filed on `ticket.mitidbok.se` (best-effort; DB row is the
   authority). Requeue with `flask webhook requeue --guid <guid>`.

Other `flask webhook` subcommands: `tick`, `list-pending`, `requeue`.

### 5.5 Consent-at-dispatch PDL gate (`dispatch_service.py`, #229)

Before forwarding a dispatch upstream to plan.pdhc, `create_dispatch()`
enforces cohesive-care consent (**Lag 2022:913 §5**) via
`ips_consent_client.py`:

- When the caller supplies **both** `patient_guid` and
  `destination_caregiver_guid`, request.pdhc fetches the patient's active
  consents from ips.pdhc (`/api/v1/patients/<guid>/consents`, 30 s TTL cache)
  and checks `consent_covers_dispatch()`:
  - at least one active consent must name the destination caregiver
    (`no_consent` otherwise);
  - a whole-caregiver consent covers any payload; a concept-narrowed consent
    covers only its listed `consented_concept_guids` — a payload concept
    outside that set is refused (`concept_not_consented`).
- A refusal returns **403 `consent_missing`** and writes a
  `careplan.dispatch.refused` audit row (with `pdl_basis: Lag (2022:913) §5`).
  The gate runs **before** the idempotency check so a consent-failing dispatch
  can't "succeed" by replaying a prior idempotency key.
- Supplying only one of the two fields logs a warning but does **not** refuse
  (soft-rollout posture).

### 5.6 Report validation chain (defense in depth)

For a provider report arriving at gateway.pdhc and validated back through
request.pdhc:

1. PAT validates provider identity → derives `provider_org_guid`.
2. Grant token validated via `/internal/grant/validate` → `contract_guid`,
   `grant_type`, `uses_remaining`.
3. SR context fetched via `/internal/service-request/<sr>/context`.
4. Patient cross-check — body's `patient_guid` must match the SR subject.
5. Concept enrichment + range checks (gateway side, from SR context).
6. Grant use recorded (`used_count++`) for audit.

Any failure aborts with 4xx + `OperationOutcome`.

## 6) Operational dependencies

| Dependency | Purpose | Failure mode |
|---|---|---|
| sso.pdhc | JWT validation, login | All UI + API auth fails. |
| ips.pdhc | Patient proxy (`patient_service`), clinic need-to-know, and **consent-at-dispatch** (`ips_consent_client`) | Patient reads 502; dispatch consent fetch fails **open-to-refuse** only when both consent fields are supplied (empty consents → `no_consent`). |
| plan.pdhc | PlanDefinition snapshot + dispatch (`/api/v1/PlanDefinition/<guid>/dispatch`) | SR create / dispatch degrades; dispatch marked `failed`. |
| contract.pdhc | Contract status lookup + PAT auto-provision | New SR creation gated on contract status. |
| provider webhook URLs | Outbound `service_request.dispatched` notifications | Retried with backoff; `dead_letter` + ops ticket after 6 attempts. |
| ticket.mitidbok.se | Webhook DLQ ops tickets | Best-effort; DB row still records the dead-letter. |

## 7) Why this split

- **Identity** in sso.pdhc → one login authority.
- **Patients** in ips.pdhc → one patient registry + consent store; request.pdhc
  proxies, never copies.
- **Contract** in contract.pdhc → governance boundary.
- **Templates** (PlanDefinition/CarePlan) authored in plan.pdhc → request.pdhc
  snapshots them so issued SRs are immutable against later template edits.
- **Gateway** in gateway.pdhc → single ingestion choke-point for provider
  observation traffic; the HMAC secret stays in request.pdhc via delegated
  grant validation.

`request.pdhc` is the orchestrator that ties them together for the
clinical-lead UX.

## Port Allocation

All ports bind to `127.0.0.1` (loopback only); external traffic arrives
via the reverse proxy.

| Port | Service |
|------|---------|
| 9060 | Flask application (Gunicorn) |
| 9061 | PostgreSQL database |