analyse.pdhc — technical documentation

Purpose

analyse.pdhc is the GROUP / population + federated-events half of the old
dashboard, extracted into its own FHIR-R5 microservice (docs/470_scoping.md).
It hosts:

• the researcher / cohort engine (define a cohort by a JSON predicate,
  resolve members across the CDR federation, then histogram / boxplot /
  scatter / trend / CSV-export aggregations), and
• the gateway/monitor-facing federated endpoints (/api/v1/observations
  #291; /api/v1/stats, /api/v1/canonical/<table>, /api/v1/openehr/* #292).

It is gated on the ANALYSIS phase. The individual / point-of-care half
(nurse, /charts, patient single-view, CDR1 care-delivery reads) lives in
cd-assist (host dashboard.pdhc.se, unchanged) and is deliberately absent here.

Architecture

browser ──SSO login──▶ /auth/login → sso.pdhc → /auth/callback (session token)
                        │
gateway.pdhc ──svc-key──┤ before_request loader (app/auth.py)
monitor.pdhc ──svc-key──┤   • service-key   → service blob (service_source)
                        │   • AUTH_MODE=off  → dev-SU blob
                        │   • AUTH_MODE=sso  → re-validate bearer every request
                        ▼   • gate: has_analysis_access (SU OR prof+analysis)
        ┌───────────────────────────────────────────────┐
        │ researcher_api  (/api/cohort…)  researcher_required + @audit_read
        │ observations_search (/api/v1/observations)  service_source gated
        │ analyse_stats / canonical / openehr (/api/v1/…) service_source gated
        └───────────────────────────────────────────────┘
                        │  app/analyse/federation.fanout (ThreadPool)
                        ▼  X-Source-Service: analyse.pdhc + ANALYSE_PDHC_SERVICE_KEY
                    CDR2 … CDR6   (/api/v1/fhir/Observation, /api/v1/stats, …)

Auth (app/auth.py)

• has_analysis_access(blob) = is_su_admin OR (user_type == "professional"
  AND "analysis" in session_phases, dual-read effective_phases).
• install_request_loader — one before_request. Order: public paths
  (/auth/*, /healthz, /api/v1/health, /static/*) → service-key
  (KNOWN_SERVICES) → AUTH_MODE=off dev-SU → SSO bearer re-validated on
  every request against sso.pdhc /api/auth/me/service (Rule 11, no blob
  cache) → has_analysis_access gate.
• KNOWN_SERVICES = {monitor.pdhc: MONITOR_PDHC_SERVICE_KEY, gateway.pdhc: GATEWAY_PDHC_SERVICE_KEY} — each sibling presents its own key.
  Service callers get a machine blob with service_source set and NO clinical
  roles / admin bit, so they can reach ONLY the federated /api/v1/* endpoints
  (which self-gate on service_source); the researcher UI (researcher_required)
  needs a real operator session.
• ANALYSE_PDHC_SERVICE_KEY is analyse's OWN outbound identity to CDR2–6 (set
  in the federation fanout), distinct from the inbound keys above.

Web login (app/routes/auth.py, ported from dashboard.pdhc)

/auth/login → sso.pdhc (anti-CSRF state), /auth/callback validates the
returned token, admits only has_analysis_access, stores session['sso_token']
(re-validated each request by the loader), /auth/logout clears + revokes.
/ renders the researcher workspace shell (routes/views.py).

Read core (app/analyse/federation.py + aggregations.py)

Copied from dashboard.pdhc (source of truth per decision D5 — mirror any fix
across dashboard/cd-assist/analyse). CdrRegistry.from_config reads
CDR_ENDPOINTS; fanout calls every CDR concurrently with per-CDR timeout and
partial-result tolerance (mode = complete|degraded|error). Aggregators:
merge_histograms, merge_agp_bands, concat_series, lttb_downsample;
aggregations.compute_stats/compute_agp produce the cdr1-shaped Parameters the
mergers consume.

Consent (app/services/ips_client.py)

Cohort member sets pass through ips.pdhc's analysis-filter (purpose=research)
before persist/aggregate — ips owns the consent flags (D1 #404); the verdict is
never computed locally and fails closed (503) if ips is unreachable.
analyse calls it with ANALYSE_PDHC_SERVICE_KEY.

Data model (app/models)

• users — local SSO-caller mirror; flask create-su bootstrap (Rule 23).
• cohort — persisted cohort definitions (guid, filter JSONB, members JSONB,
  n, owner_label, created_at). Ported column-for-column from dashboard.
• analyse_audit — read-side PDL Ch 4 §3 kontroller log, one row per
  patient/aggregate-touching read incl. 4xx denials (@audit_read). Ported
  from dashboard's dashboard_audit; X1 tuple (person/role/purpose/access_basis)
  in payload_snapshot, purpose route-classed (research for /api/cohort).

JSONB is dialect-aware (real JSONB on Postgres, plain JSON on SQLite for the
hermetic test suite). Single alembic head 0001_initial.

Config (analyse_app/.env.example)

APP_PORT=9110, DB_PORT=9111 (127.0.0.1 only), COMPOSE_PROJECT_NAME=analyse_pdhc,
AUTH_MODE, SSO_*, GATEWAY_PDHC_SERVICE_KEY, MONITOR_PDHC_SERVICE_KEY,
ANALYSE_PDHC_SERVICE_KEY, IPS_BASE_URL, CDR_ENDPOINTS (comma-sep;
https://cdrN.pdhc.se or cdrN=http://127.0.0.1:PORT), CDR_FANOUT_TIMEOUT.

Run / test

• Local container: cp analyse_app/.env.example analyse_app/.env (fill secrets),
  ./start.sh. Loopback-only; migrations run in the container entrypoint.
• Tests (offline): cd analyse_app && PYTHONPATH=. .venv/bin/python -m pytest -q
  → 38 passed. SQLite in-memory StaticPool, AUTH_MODE=off, CDR fanout + SSO
  revalidation + ips consent all patched.

Deploy / cutover

Server layout CLAUDE.md §7. Hard follow-ups: #540 gateway
ANALYSE_BASE_URL repoint, #541 CDR2–6 read-identity flip, #543 delete
the group half from dashboard(cd-assist). See readme.md.

Port Allocation

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

Port	Service
9110	Flask application (Gunicorn)
9111	PostgreSQL database