termbank.pdhc — Technical description

Bulk canonical terminology store for the PDHC platform. Read-only over
HTTP; mutations happen only through the import CLIs. This document
describes the service as it is deployed today (read API + seven
importers, FHIR conformance hardened under rollups #347 / #374).

Role in PDHC

termbank.pdhc imports upstream vocabularies as-is and serves them
read-only. It owns the canonical URI namespace
https://termbank.pdhc.se/CodeSystem/<system>/<code> (Rule 27). No
other service mints canonical URIs: plan.pdhc mirrors the subset it
curates into its working set, rosetta.pdhc stores mappings that point
at these URIs, and downstream data services (cdr.pdhc, forms.pdhc,
1177.pdhc, request.pdhc) reference them.

Imported vocabularies (seven importers, one system each):

system	Importer script	Source
loinc	scripts/import_loinc.py	LOINC release table
snomed	scripts/import_snomed.py	SNOMED CT Managed Service SE (RF2)
icd10	scripts/import_icd10.py	ICD-10-SE
atc	scripts/import_atc.py	ATC (Läkemedelsverket / SeNSL)
kva	scripts/import_kva.py	KVA medical (KMA) + surgical (KKA) procedures
socialstyrelsen	scripts/import_sosstyr.py	Socialstyrelsen termbank (full XML)
icf	scripts/import_icf.py	ICF

There is no ICD-11 importer.

FHIR conformance scope

Deliberately narrow (Rule 15): termbank implements CodeSystem
$lookup plus a /fhir/metadata CapabilityStatement, and nothing
else FHIR-shaped. ValueSet + $expand / $validate-code, ConceptMap +
$translate, and TerminologyCapabilities are out of scope by design
— that curated terminology layer lives in plan.pdhc. See
docs/decisions/ADR-001-scope-rule15.md.

Data model

Five tables (app/models/__init__.py):

• concepts — primary canonical row. Primary key is
  canonical_uri itself (no numeric surrogate leaks out; Rule 27 /
  Rule 18). Columns include system, code (unique together via
  uq_concept_system_code), display, provenance (source,
  source_url, version), lifecycle (status ∈
  active|retired|experimental, imported_at, retired_at),
  parent_uri (hierarchy, null for flat vocabularies), and an
  import_run_id FK.
• concept_designations — localised displays. (concept_uri, language, value) unique; use_code (e.g. preferred, fsn,
  synonym) drives displayLanguage selection.
• concept_properties — source-specific attributes. key / value
  / value_type ∈ string|code|integer|decimal|boolean|dateTime;
  value_type maps to the right FHIR value[x] field on output.
• import_runs — per-import bookkeeping (source, version,
  source_url, timings, status ∈ running|completed|failed|cancelled,
  concepts_imported / concepts_failed, operator, notes).
• audit_log — Rule 24 operation log (actor, action, target,
  request_id, JSON details).

ConceptDesignation and ConceptProperty cascade-delete with their
parent concept.

HTTP API

Routes live in app/api/terminology.py; the app factory and read-only
guard are in app/__init__.py.

GET /fhir/metadata

FHIR R5 CapabilityStatement. Advertises CodeSystem $lookup as the
headline operation, plus the shortcut/auxiliary routes and the
termbank-search OperationDefinition. CapabilityStatement.date is
derived from the module file's mtime (not datetime.now()) so it is
identical across gunicorn workers and only advances on an image rebuild
(finding §1.4 / #352).

GET|POST /fhir/CodeSystem/$lookup (and /fhir/CodeSystem/%24lookup)

The primary operation. Parameters:
- system (required), code (required)
- displayLanguage (optional)

On GET these are query params; on POST they come from a FHIR
Parameters request body (_extract_from_parameters_body, accepting
valueUri / valueUrl / valueCode / valueString). The %24
(URL-escaped $) path variant is registered for clients that emit it.
Missing system/code → 400 OperationOutcome; no match → 404.
Success → a FHIR Parameters resource.

GET /CodeSystem/<system>/<code>

Convenience path equivalent to $lookup. <code> is captured with a
<path:...> converter so codes containing / work. Supports
displayLanguage. Same Parameters response / 404 behaviour.

GET /Concept?uri=<canonical_uri>

Lookup by canonical URI. The URI is a query parameter (?uri=...),
not a path segment. Missing uri → 400; no match → 404. Supports
displayLanguage. Same Parameters response.

GET /search?q=&system=&limit=&displayLanguage=

Fuzzy, ranked search across Concept.display and designation values in
a single query. q required (empty → empty result set). system
repeatable or comma-separated. limit default 20, clamped to 1..200.
Rank tiers: exact code/display/designation match (1) → display prefix
(2) → preferred-designation prefix (3) → display/designation contains
(4) → designation contains (5); ties broken by active status, then
display length, then canonical URI. Response is plain JSON
({query, systems, system, count, results[]}), not a FHIR Bundle.

GET /health

DB reachability plus a per-source version/staleness summary. Returns
200 / status: "ok" when SELECT 1 succeeds, 503 /
status: "degraded" otherwise (CLAUDE.md §10 shape). Each source row
carries version, concept_count, the pinned <SOURCE>_VERSION env
value, and a stale flag when the pin and the loaded version differ.
version reports TERMBANK_GIT_SHA (default dev).

Response shapes

• $lookup / /CodeSystem/<system>/<code> / /Concept → FHIR R5
  Parameters: name (= system), version, display, then
  property parameters for code, status, optional parent /
  deprecationDate, and termbank-scoped canonical-uri, source,
  source-url, followed by designation and per-property parameters.
  Concept-level fields are surfaced as spec property parameters, not a
  non-standard _meta envelope (#351).
• Errors → FHIR OperationOutcome.

Read-only enforcement (Rule 6)

A before_request hook returns 405 (OperationOutcome, code
not-supported) for any POST/PUT/PATCH/DELETE, except the
two $lookup POST endpoints (/fhir/CodeSystem/$lookup and
/fhir/CodeSystem/%24lookup), which are reads with no side effects.
GET/HEAD/OPTIONS always pass.

Import CLIs

Each importer parses upstream, builds concepts + designations +
properties, and writes them through the shared importer_base.py
upsert. Every importer requires --source-url and --version;
--operator and --batch-size (default 2000) are optional everywhere.
File-input flags differ by source:

Importer	Required file flag(s)
import_loinc.py	--local-file
import_icd10.py	--local-file
import_atc.py	--local-file
import_icf.py	--local-file
import_snomed.py	--release-dir (RF2 release folder)
import_kva.py	--kma-file and/or --kka-file (at least one)
import_sosstyr.py	--local-file optional (downloads from --source-url otherwise)

There are no --release-csv / --release-tsv flags. Idempotency
(Rule 27): re-running with an already-imported --version is a no-op; a
new --version updates concepts in place while preserving each
canonical_uri.

Example invocations are in docs/user_manual.md.

Configuration & deployment

• Ports: 9010 reserved · 9011 PostgreSQL (container 5432 mapped to
  127.0.0.1:9011) · 9012 Flask app · 9013 reserved.
• Containers (docker-compose.yml): termbank_pdhc_db
  (postgres:16, volume termbank_pdhc_pgdata) and termbank_pdhc_app
  (built from Dockerfile). Pin COMPOSE_PROJECT_NAME=termbank_pdhc so
  release swaps don't orphan the data volume.
• Config (app/config.py, .env.example): DATABASE_URL
  (default postgresql+psycopg2://termbank:changeme@localhost:9011/termbank_pdhc_db),
  CANONICAL_URI_BASE (default https://termbank.pdhc.se), SECRET_KEY,
  and the per-source <SOURCE>_VERSION pins consumed by /health.
• AUTH: AUTH_MODE=off — the read API is public (Rule 24), so there
  is no SSO gating on this service.
• SECRET_KEY guard (#354): startup refuses the placeholder
  SECRET_KEY in production; pytest is exempt via TESTING=True.
• Migrations: Alembic under migrations/ (flask db upgrade).

Tests

app/tests/ covers the read API, health, models, per-importer parsing,
and a test_capability_truth.py conformance check that keeps the
CapabilityStatement honest against the routes actually registered. The
Postgres-only search ranking (func.least) is deselected on SQLite via
make test (-k "not search"); make test-all runs everything against
Postgres. make corpus / make conformance emit and validate $lookup
+ CapabilityStatement samples against the HL7 R5 validator.

Port Allocation

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

Port	Service
9012	Flask application (Gunicorn)
9011	PostgreSQL database