Amy-Term User Guide

1. Purpose

Amy-Term is a self-contained terminology platform designed for national and enterprise deployments, including environments with intermittent connectivity.

What it provides

• Internal persistence for CodeSystems, Concepts, ValueSets and ConceptMaps
• FHIR-style terminology operations (such as $lookup, $expand, $translate)
• SNOMED CT integration (Snowstorm proxy browser and related operations)
• Federation to export selected artefacts and replicate to regional nodes

GET /fhir/metadata
Accept: application/fhir+json

GET /health
Accept: application/json

2. Roles and access

Amy-Term distinguishes between viewer and admin roles. Viewer users can browse and use most read APIs, while admin users can import, curate and export.

Typical access patterns

• Viewer: browse CodeSystems/ValueSets/ConceptMaps, run searches, use FHIR terminology operations
• Admin: import content, manage artefacts, run federation capture, export bundles, configure node identity

GET /codesystems
GET /valuesets
GET /tools

3. CodeSystems

A CodeSystem is where the concepts (codes) live. Examples include ICD-10-GM, OPS, LOINC, ATC, and local code lists.

UI

• Browse and manage: /codesystems
• View concepts (where implemented): follow the UI actions from the CodeSystems list

GET /fhir/CodeSystem/$lookup?system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05
Accept: application/fhir+json

GET /fhir/CodeSystem/$lookup?system=http://fhir.de/CodeSystem/atc-gkv&version=2025&code=A02AA05
Accept: application/fhir+json

If you support a local CodeSystem URL, you can use that as the system parameter.

4. ValueSets

A ValueSet is a curated selection of codes (typically from one or more CodeSystems). It is used for searching, validation, and decision logic.

UI

• Browse and edit: /valuesets
• Design studio (recommended for authoring): /tools

GET /fhir/ValueSet/$expand?url=http://amterm.local/fhir/ValueSet/example
Accept: application/fhir+json

GET /fhir/ValueSet/$validate-code?url=http://amterm.local/fhir/ValueSet/example&system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05
Accept: application/fhir+json

If your installation supports paging parameters for expand, use them for large ValueSets.

5. ConceptMaps

ConceptMaps define mappings between code systems (for example ICD-10-GM → SNOMED CT, or local codes → national codes). Amy-Term supports ConceptMap authoring and translation operations.

UI

• ConceptMap authoring: /tools (Tools & Designer)
• ConceptMap list (where implemented): link from Tools & Designer

GET /fhir/ConceptMap/$translate?source=http://fhir.de/CodeSystem/icd-10-gm&target=http://snomed.info/sct&code=F20.0
Accept: application/fhir+json

GET /fhir/ConceptMap/$translate?url=http://amterm.local/fhir/ConceptMap/icd10gm-to-snomed&code=F20.0
Accept: application/fhir+json

6. ATC (German GKV/WIdO and WHO)

ATC is supported as a normal CodeSystem with optional enrichment properties (for example German therapeutic headings and DDD text). Use the ATC browser to search by code or display and to access $lookup.

UI

• ATC browser: /atc/browser
• ATC import (admin): /atc/import

GET /atc/browser?q=A02AA05
GET /atc/browser?q=omeprazole
GET /atc/browser?system=http://fhir.de/CodeSystem/atc-gkv&q=A02AA05

GET /fhir/CodeSystem/$lookup?system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05
Accept: application/fhir+json

7. SNOMED CT (Snowstorm integration)

SNOMED CT is typically integrated through Snowstorm. Amy-Term provides a UI entry point and proxy endpoints depending on your setup.

UI

• SNOMED browser: /snomed
• Branch management and expansions: use your SNOMED tooling pages (if enabled)

GET /snomed/search?term=schizophrenia&limit=20
Accept: application/json

Use the “Normalize expression” button to call /snomed/expressions/transform before searching; the UI puts the normalized expression back into the ECL field so you can expand it reliably.

If your SNOMED integration runs through a dedicated Snowstorm service, you will also monitor that stack (Elasticsearch/Snowstorm).

8. Federation (central → regional distribution)

Federation is used to export and replicate selected CodeSystems, ValueSets and ConceptMaps. This is designed for offline or intermittently connected regions.

Important operational model

• Capture the artefacts you want to distribute: /federation/capture
• Export bundles from the captured set: /federation/bundles/export
• Apply bundles on regional nodes: /federation/bundles/apply

GET /federation/capture

GET /federation/bundles/export?namespace=default&mode=artifacts&limit=200&include_payload=true&sign=true
Accept: application/json

POST /federation/pull/run?central_base_url=https://central.example.org&namespace=default&limit=500&apply_to_store=true&store_artifacts=true
Accept: application/json

POST /federation/bundles/apply?direction=import&store_artifacts=true&apply_to_store=true
Content-Type: application/json

{
  "bundle": {
    "bundleType": "federation",
    "manifest": { },
    "artifacts": [ ]
  }
}

9. Metrics and monitoring

Use the metrics dashboard to monitor usage, request volumes and operational errors. Ensure you also monitor your database and (if enabled) Snowstorm/Elasticsearch.

UI

• Metrics dashboard: /metrics

GET /codesystems
GET /valuesets
GET /atc/browser?q=A02AA05
GET /fhir/metadata
GET /fhir/CodeSystem/$lookup?system=http://fhir.de/CodeSystem/atc-gkv&code=A02AA05

10. Troubleshooting

Common symptoms

• 422 validation error when searching: typically duplicate query parameters or invalid parameter types.
• Not authenticated JSON response: prefer redirecting to login for UI routes.
• Slow browsing: enable paging and ensure indexes exist on large tables.

422 on ATC browser search

If you see a request like ...&limit=20...&limit=50, FastAPI will reject it with 422 because the query parameter appears twice. Ensure your forms and links only include each parameter once.

GET /atc/browser?q=A02AA05&limit=50&offset=0

Authentication for UI routes

UI pages should redirect to the login page if the session is not active. API endpoints should return JSON errors.