# Architecture — request.pdhc

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

## 1) What this service is

**request.pdhc** is the patient-record + service-request layer of the PDHC platform. It owns:

- Local pseudonymised patient cache.
- The `ServiceRequest` lifecycle (create → active → dispatched → completed/revoked).
- The `DataExchangeGrant` HMAC-signed composite key that lets a specific provider report on a specific SR.
- Care-plan grouping and clinical-lead reporting.
- The audit trail for every state-changing action.

It does **not** own:

- Identity (sso.pdhc).
- Contract terms (contract.pdhc).
- Inbound observation routing (gateway.pdhc).
- Terminology / canonical URIs (termbank.pdhc).

## 2) Container topology

```
                                                                
  Browser ──HTTPS──▶ nginx (miserver) ──▶ request_pdhc_app:9060 ──▶ request_pdhc_db:9061
                              │                       │
                              │                       └─▶ contract.pdhc:9021 (status check)
                              │                       └─▶ sso.pdhc:9000 (token validation)
                              │
                              └────▶ provider feed / push to provider1.pdhc, cgm.pdhc, ...
                                                              │
                                          ◀── reports via gateway.pdhc:9050 ◀──┘
```

- `request_pdhc_app` — Flask + gunicorn, in Docker.
- `request_pdhc_db` — PostgreSQL 16, in Docker, host port 9061 forwarded.
- All non-trivial cross-service calls go via `host.docker.internal` from inside Colima.

## 3) Data flow — happy path

```
Requester               request.pdhc        contract.pdhc       provider              gateway.pdhc
─────────              ─────────────       ──────────────      ──────────            ──────────────
POST /service-requests
  body: SR + contract_guid
   ─────────▶
                       validate contract
                          ─────────────────▶ GET /Contract/<guid>
                          status==executed?
                          ◀──── 200 ────────
                       persist SR (active)
                       mint DataExchangeGrant
                       push FHIR Bundle ───────────────────────▶ POST /inbound/push
                                                                  202 Accepted
                       mark dispatched
   ◀──── 201 ────────
                                                                  ... fulfill ...
                                                                POST /report/<sr_guid>
                                                                  X-Provider-Token + grant
                                                                                      ────────────▶
                                                                                      validate PAT
                                                                                      validate grant
                                                                                      ◀── /internal/grant/validate
                                                                                      enrich + persist obs
                       observation pushed back     ◀────────────────────────────────────
                       SR → completed
```

## 4) Data model

### 4.1 Patient (cached)

| Column | Type |
|---|---|
| `guid` | UUID v4 (matches upstream pseudonym) |
| `identifier` | JSONB |
| `organisation_guid` | FK to upstream org GUID (no FK constraint — sso.pdhc is the source of truth) |
| `created_at`, `updated_at` | timestamptz |

### 4.2 ServiceRequest

| Column | Type | Notes |
|---|---|---|
| `guid` | UUID v4 | |
| `subject_patient_guid` | UUID v4 | |
| `performer_org_guid` | UUID v4 | |
| `based_on_contract_guid` | UUID v4 | required; gates SR validity |
| `status` | enum | `draft / active / in-progress / completed / revoked` |
| `transactions` | JSONB | `[{concept_canonical, requirement, value_constraints}]` |
| `occurrence_start`, `occurrence_end` | timestamptz | |
| `dispatched_at`, `completed_at`, `revoked_at` | timestamptz | |
| `revoke_reason` | text | |
| `created_at`, `updated_at` | timestamptz | |

### 4.3 DataExchangeGrant

HMAC-signed composite key allowing one provider to report on one SR.

| Column | Type | Notes |
|---|---|---|
| `grant_token` | text | HMAC-SHA256 of (SR + patient + provider_org + contract + expires_at) |
| `service_request_guid` | UUID v4 | |
| `patient_guid` | UUID v4 | |
| `provider_org_guid` | UUID v4 | |
| `contract_guid` | UUID v4 | empty string if direct delivery (no Contract) |
| `grant_type` | enum | `pull` (provider polls) / `push` (gateway delivers) |
| `expires_at` | timestamptz | |
| `uses_remaining` | int | 1 by default; bump for re-fetch / replay |

The HMAC secret (`HMAC_SECRET`) is held **only** by request.pdhc. Gateway.pdhc never sees the secret — it delegates validation to request.pdhc's `/internal/grant/validate`.

### 4.4 CarePlan

Optional grouping layer over multiple SRs (longitudinal goals, cohort reporting).

### 4.5 AuditLog

Append-only. Columns: `actor_user_guid, action, resource_type, resource_guid, before_json, after_json, at`.

#### 4.5.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.

| Method | URL rule | `action` | `resource_type` | Wired via |
|---|---|---|---|---|
| GET | `/api/v1/Patient` | `patient.list` | `Patient` | `@audit_read` (#227) |
| GET | `/api/v1/Patient/<guid>` | `patient.read` | `Patient` | `@audit_read` (#227) |
| GET | `/api/v1/CarePlan` | `careplan.list` | `CarePlan` | `@audit_read` (#227) |
| GET | `/api/v1/CarePlan/<guid>` | `careplan.view` | `CarePlan` | inline `log_event` (pre-#227) |
| GET | `/api/v1/ServiceRequest` | `service_request.list` | `ServiceRequest` | `@audit_read` (#227) |
| GET | `/api/v1/ServiceRequest/<guid>` | `service_request.read` | `ServiceRequest` | `@audit_read` (#227) |
| GET | `/api/v1/ServiceRequest/<guid>/matches` | `service_request.matches.list` | `ServiceRequest` | `@audit_read` (#227) |
| GET | `/api/v1/ServiceRequest/<guid>/receipts` | `service_request.receipts.list` | `ServiceRequest` | `@audit_read` (#227) |
| GET | `/api/v1/ServiceRequest/<guid>/forms` | `service_request.forms.list` | `ServiceRequest` | `@audit_read` (#227) |
| GET | `/api/v1/ServiceRequest/receipt/<token>` | `service_request.receipt.read` | `ServiceRequestReceipt` | `@audit_read` (#227) |
| GET | `/api/v1/requests` | `request.list` | `ServiceRequest` | `@audit_read` (#227) |
| GET | `/api/v1/requests/<guid>` | `request.read` | `ServiceRequest` | `@audit_read` (#227) |
| GET | `/api/v1/provider/feed` | `feed.accessed` | (none — metadata only) | inline `log_event` |

Catalogue / metadata reads that don't carry patient identifiers
(`/Form`, `/PlanDefinition`, `/Contract`, `/providers`, `/metadata`,
`/admin/provider-tokens`, `/docs/*`, `/api`) are intentionally
out of scope — no patient-shaped data crosses them.

Authoring routes (POST / PUT / DELETE) already write inline
`log_event` rows with the matching action prefixes (`patient.create`,
`service_request.create.requested`, etc.).

##### Adding new read endpoints

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

## 5) Security

### 5.1 Auth

- **Public surface**: SSO Bearer JWT, validated on every request (no client-side caching).
- **Internal surface**: `X-Source-Service` + `X-Service-Key` pair, validated against `KNOWN_FHIR_SERVICES` config.
- **Provider surface**: `X-Provider-Token` (PAT) — opaque bearer issued by request.pdhc's PAT service, bound to (provider_org_guid, contract_guid).

### 5.2 Validation chain (defense in depth)

For a provider report submission via gateway.pdhc:

1. PAT validates provider identity → derives `organisation_guid`.
2. Grant token validated (request.pdhc) → returns `contract_guid`, `grant_type`.
3. SR context fetched (request.pdhc) → transactions, patient, goals.
4. Patient cross-check — body's `patient_guid` must match SR subject.
5. Concept enrichment — `concept_guid`/`unit` derived from SR transaction map.
6. Range check — observation values vs transaction definitions.
7. Contract scope enforcement — concepts vs `Contract.return_scope`.
8. Grant use recorded for audit.

Any failure aborts the chain with 4xx + `OperationOutcome`.

### 5.3 Data minimisation

The provider feed (`GET /provider/feed`) returns SR metadata only — no patient data. The full Bundle is delivered only after the provider downloads it (creating a Grant) or on a push, both of which are audited.

## 6) Operational dependencies

| Dependency | Purpose | Failure mode |
|---|---|---|
| sso.pdhc | JWT validation, login | All UI + API auth fails (503 on health). |
| contract.pdhc | Contract status + return_scope lookup | New SR creation fails with 422 `contract_unavailable`. Existing SRs unaffected. |
| termbank.pdhc | Canonical concept URIs (read-only) | Optional — concept lookup degrades to "unverified" but doesn't block. |
| gateway.pdhc | Inbound provider reports | Reports queue up at gateway side; request.pdhc only sees the relayed call. |

## 7) Why this split

- **Identity** in sso.pdhc → one login authority, easier compliance.
- **Contract** in contract.pdhc → governance boundary; legal review can iterate on contract template without touching SR code.
- **Gateway** in gateway.pdhc → single ingestion choke-point for all provider traffic; rate limiting / abuse detection lives there.
- **Termbank** in termbank.pdhc → terminology releases (LOINC / SNOMED / ATC) update on a different cadence than service code.

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