# rosetta.pdhc — Technical specification

Rosetta re-represents patient observations sourced from **gateway.pdhc** into
three clinical-data standards — **FHIR R5**, **openEHR**, and **OMOP CDM** —
and serves them over a web UI and a JSON REST API. It is an analysis-phase
service: SSO-gated, org-scoped, consent-enforced (fail-closed), and
audited on every read.

- Stack: Flask 3 + SQLAlchemy 2 + Flask-Migrate/Alembic, PostgreSQL 16,
  gunicorn (2 workers), `requests` for upstream calls, Jinja2 views.
- Ports: **9091** Postgres (container 5432 → host), **9092** app
  (`127.0.0.1`, behind the reverse proxy at `https://rosetta.pdhc.se`).
  9090/9093 reserved.

## 1. Data flow

```
SSO user ─Refresh─► gateway.pdhc GET /api/v1/observations?organization=<org>
                          │ (FHIR R5 bundle)
                          ▼
                   observation_cache  ──► fhir_converter   ─► fhir_representations
                                       ├─► openehr_converter ─► openehr_representations
                                       └─► omop_converter    ─► omop_measurements
                          ▼
        web UI (3 side-by-side cards)  /  REST  /api/v1/patient/<guid>/{fhir|openehr|omop}
```

Concept resolution is delegated to **plan.pdhc**: observations arrive from
gateway already FHIR-coded; Rosetta passes `concept_guid` through and records
`concept_name`, linking back via
`https://plan.pdhc.se/api/v1/concepts/<concept_guid>`. No local terminology.

## 2. HTTP API

All under the `/api/v1` prefix (blueprint `api`); SSO bearer via session.

| Method | Path | Returns |
|---|---|---|
| GET | `/patient/<guid>/fhir` | FHIR searchset `Bundle` `{resourceType, type:"searchset", total, entry:[{resource}]}` |
| GET | `/patient/<guid>/openehr` | `{patient_guid, total, compositions:[…]}` |
| GET | `/patient/<guid>/omop` | `{patient_guid, total, measurements:[{measurement_concept_id, measurement_date, measurement_datetime, value_as_number, unit_source_value, measurement_source_value}]}` |

HTML views (blueprint `views`): `GET /` (patient list, org-scoped),
`GET /patient/<guid>` (3-card detail; auto-converts if missing),
`POST /patient/<guid>/convert` (idempotent re-convert),
`POST /refresh` (sync cache from gateway).

Auth (blueprint `auth`, `/auth`): `/login`, `/callback`, `/logout`,
`/logged-out`.

Public: `GET /healthz` → `{status:"ok"|"degraded", service:"rosetta.pdhc",
database:"connected"|"unavailable", auth_mode}` (200/503, CORS for
www.pdhc.se); `GET /metadata` → FHIR R5 CapabilityStatement (fhirVersion
5.0.0).

## 3. The three converters (`app/services/`)

**FHIR R5** — `fhir_converter.to_fhir_r5(obs)`: prefers the rich FHIR from
gateway's raw JSON (basedOn / performer / referenceRange / extensions
preserved); normalises `status=final`, `subject=Patient/<guid>`,
`category=laboratory`, `meta.profile` includes the IPS profile; code system
`https://plan.pdhc.se/api/v1/concepts/<concept_guid>` + `concept_name`
display; `valueQuantity` with UCUM unit. → `fhir_representations`.

**openEHR** — `openehr_converter.to_openehr_composition(obs)`: root
`openEHR-EHR-COMPOSITION.report-result.v1` wrapping
`openEHR-EHR-OBSERVATION.laboratory_test_result.v1`; `DV_QUANTITY`
(magnitude+unit), POINT_EVENT time. → `openehr_representations`.

**OMOP CDM** — `omop_converter.to_omop_measurement(obs)`: measurement domain —
`person_id←patient_guid`, `measurement_concept_id←concept_guid`,
`measurement_date/datetime←observed_at`, `value_as_number←value` (categorical
→ `value_as_concept_id`), `unit_source_value←unit`,
`measurement_source_value←concept_name`, `measurement_source_url←plan.pdhc
concept URL`. → `omop_measurements`.

Conversion is idempotent: re-convert deletes and rebuilds all three per
patient; runs are tracked in `conversion_log`.

## 4. Data model (`app/models/__init__.py`, PostgreSQL)

| Table | Purpose |
|---|---|
| `users` | Local user mirror (FK + audit, Rule 24) |
| `observation_cache` | Raw gateway observations: `source_obs_guid` (unique), `patient_guid`, `org_guid`, `concept_guid`, `concept_name`, `value`, `unit`, `observed_at`, `raw` (JSONB) |
| `fhir_representations` | Validated FHIR R5 Observation (`resource_json`, FK → cache) |
| `openehr_representations` | openEHR Composition (`archetype_id`, `composition_json`) |
| `omop_measurements` | OMOP measurement row (`person_id`, `measurement_*`, `measurement_source_url`) |
| `conversion_log` | Per-patient conversion runs (status, fhir/openehr/omop counts) |
| `refresh_log` | Gateway sync runs (rows_fetched, status) |
| `audit_log` | X1 (#407) read audit tuple (see §6) |

Migrations: `ad445ccc0480` initial schema; `b7f2a1c3d901` adds
`omop_measurements.measurement_source_url`.

## 5. Auth & org scoping (`app/auth.py`)

- **AUTH_MODE=off** (dev): no login; dev SU user, `effective_phases=["analysis"]`.
- **AUTH_MODE=sso** (prod): token forwarded to gateway as
  `Authorization: Bearer`; validated against
  `sso.pdhc.se/api/auth/me/service` with `SSO_CLIENT_ID`/`SSO_CLIENT_SECRET`.
- **Phase gate** `has_analysis_access()`: `user_type=="professional"` **and**
  "analysis" in `session_phases` (legacy fallback `effective_phases`); SU
  admins auto-pass.
- **Zone-1 org scope (M0 #417)**: non-admins filtered by
  `affiliations[].care_unit_guid` (legacy fallback `organization_ids`) via
  `scope_to_user_orgs()`; admins unscoped and may seed refresh from
  `DEFAULT_ORG_GUIDS`.

## 6. Consent, audit, session propagation

- **Consent (#422), fail-closed** — `analysis_consent.check_patient_allowed()`
  calls ips.pdhc `POST /api/v1/patients/analysis-filter` (contract in
  `plans/pdhc_data_shapes.md §5`). Purpose is derived from the active role:
  research role → `research` (+ `research_project_guids`); quality/registry →
  `quality_registry`; other clinical → `statistics`; SU-admin-no-affiliation →
  `administration`. **No verdict → HTTP 503, no data.** Applied to every
  patient read (views + API).
- **X1 read audit (#407)** — `x1_audit` writes an `audit_log` row per read:
  `person_guid, role_guid, purpose, access_basis, route, n_rows, session_id`.
- **X2 session propagation (#408)** — `session_headers` adds
  `X-Operator-Session-Id` (from forwarded header, else SSO blob `session_id` /
  JWT `sid`) to every onward gateway/ips call, for end-to-end kontrollör audit.

## 7. Configuration (`.env`)

```
APP_PORT=9092
DB_HOST / DB_PORT=9091 / DB_NAME=rosetta_pdhc_db / DB_USER / DB_PASSWORD
DATABASE_URL=postgresql+psycopg2://…:9091/rosetta_pdhc_db
AUTH_MODE=off|sso
SSO_BASE_URL=https://sso.pdhc.se   SSO_CLIENT_ID / SSO_CLIENT_SECRET
SSO_CALLBACK_URL=https://rosetta.pdhc.se/auth/callback
GATEWAY_BASE_URL=https://gateway.pdhc.se
IPS_BASE_URL=https://ips.pdhc.se   # #422 consent; fail-closed if unset
SECRET_KEY / DEFAULT_ORG_GUIDS
```

## 8. Deployment

Single `db` service via docker-compose (postgres:16); app runs under gunicorn
via `./start.sh`:

- Kills the previous gunicorn (PID file under `.shared/`), ensures Docker/DB
  up, runs `flask db upgrade`.
- Launches gunicorn: 2 workers, 120 s timeout, 500 max-requests/worker, bound
  to `127.0.0.1:9092`; logs under `.shared/logs/`.
- Bounded `/healthz` smoke (10×1 s) before declaring up.
- Reverse proxy terminates TLS and forwards to `127.0.0.1:9092` at
  `rosetta.pdhc.se`.

## 9. Tests (`app/tests/`)

`test_scaffold` (/healthz, /metadata), `test_converters` (all three
converters), `test_analysis_consent` (purpose derivation + ips filter),
`test_reform_scope` (Zone-1 org scoping), `test_session_propagation`
(X-Operator-Session-Id), `test_x1_audit` (audit tuple).