Gateway.pdhc — User Guide (Non-Technical)

What is the Gateway?

The PDHC Gateway is the central point where healthcare providers submit their measurement data back to the healthcare system. When a doctor creates a care plan for a patient and assigns a provider to carry out measurements, the provider uses the gateway to report results.

How it works

1. A care plan is created — A doctor creates a service request with a care plan for a patient
2. A provider is assigned — The request system matches the care plan to a contracted provider
3. The provider gets a token — The provider receives a secure access token (PAT) that proves their identity
4. Measurements are taken — The provider carries out the care plan activities
5. Data is submitted — The provider's system sends the measurement data to the gateway
6. Receipt is issued — The gateway validates the data and sends a receipt back to the provider
7. Data is resolved — The gateway connects the measurements back to the original care plan, giving clinical meaning to the raw values

Key concepts

• PAT (Provider Access Token): A secure token that identifies the provider. Issued by the request system.
• Composite key: Four identifiers (patient, contract, organisation, service request) plus a cryptographic grant token that prove the provider is authorized to submit this specific data.
• Receipt: Confirmation sent back to the provider that data was received (accepted or rejected).
• GUID chain resolution: The process of connecting a measurement value back through the care plan to the original clinical template, giving it medical meaning.

The observations page

The gateway provides a web interface at /observations where administrators can:
- View all incoming data with timestamps
- Filter by patient identifier
- See whether receipts have been sent
- See whether the data has been resolved and connected to care plans
- Click individual observations to see full details including the FHIR JSON

Cache Management (/admin/cache)

The gateway caches upstream lookups (service request context, contract scope, PAT validation results) so it doesn't re-fetch on every request. Caches expire automatically via TTL, but sometimes a stale entry causes problems — for example, if a service request's plan was updated upstream but the gateway still has the old version cached.

When to use it:
- Observations are failing validation and you suspect the gateway has outdated transaction or contract data
- You've changed something in request.pdhc or contract.pdhc and need the gateway to pick it up immediately
- You see "VALIDATION_ERROR" or "SCOPE_VIOLATION" rejections that shouldn't be happening

What you can do:
- Flush stale — removes only entries that have exceeded their TTL. Safe, no disruption. The gateway will re-fetch from upstream on the next request that needs the data.
- Flush all (per type or global) — removes all cached entries. Causes a brief increase in upstream calls as the cache refills. Use when you need to force a complete refresh.

Cache types:
- sr_context — service request transactions and goals (TTL: 1 hour)
- contract_scope — obligatory/optional concepts per contract (TTL: 60 seconds)
- pat_validation — provider token validation results (TTL: 1 hour)
- service_request — full service request data (TTL: 1 hour)

Health Report (/admin/health-report)

Live connectivity check for all upstream services the gateway depends on. Shows:

• Service probes — whether request.pdhc, contract.pdhc, sso.pdhc, and the local database are reachable, with latency and database status
• Recent errors (24h) — PAT rejections, report rejections, and push delivery failures from the audit log

When to use it:
- After a deploy or restart, to verify all connections are working
- When providers report submission failures — check if an upstream service is down
- To diagnose patterns in rejections (e.g. a specific provider org getting repeated PAT rejections)

Click "Re-check now" to re-probe all services.

Security

• All data transmission requires authentication
• Provider identity is verified cryptographically, never from request parameters
• All actions are logged in a GDPR-compliant audit trail
• Patient data is identified by secure identifiers, not personal information