Terminology Service — Service Overview
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The terminology-service is the canonical coded-value resolution layer for the Ghasi-eHealth platform. It provides a shared, multi-tenant terminology server so that every clinical service can look up, validate, and expand standard medical codes without duplicating terminology data or licensing.
It owns the runtime query surfaces for SNOMED CT, LOINC, ICD-10-CM (including the Afghanistan national adaptation), RxNorm, and tenant-scoped custom value sets. It also owns the clinical decision support primitives: drug-drug interaction checking, drug class classification, duplicate therapy detection, and drug-condition contraindication checking.
2. Source Reconciliation
| Legacy module | Contribution |
|---|---|
_sources/terminology/SPEC.md | All FRs (FR-TERM-001..012), NFRs, business rules, data model, API surface |
_sources/terminology/EVENT_MODEL.md | Published events and NATS subject taxonomy |
_sources/terminology/backlog/EPICS.md | Existing epic structure (TERM-EPIC-01..06, TERM-ENH-EPIC-01..03) |
3. Bounded Context
| Attribute | Value |
|---|---|
| Bounded context | Platform shared services |
| DDD classification | Shared kernel (read-only for most consumers) |
| Module entitlement key | platform.terminology (always-on baseline service) |
| NestJS package | @ghasi/terminology-service |
| Client package | @ghasi/terminology-client (used by all clinical services) |
4. Responsibilities
- Full-text concept search within a coding system by code or display text (FR-TERM-001)
- Exact code lookup by
system + codereturning display, definition, and active status (FR-TERM-002) - Code validation — active/inactive status check (FR-TERM-003)
- ValueSet expansion to constituent active concepts (FR-TERM-004)
- Drug class lookup by RxNorm code (FR-TERM-005)
- Drug-drug interaction checking with severity classification (FR-TERM-006)
- Tenant-scoped custom concept governance (FR-TERM-007, FR-TERM-008)
- Bulk concept import via admin API or ETL pipeline (FR-TERM-009)
- Duplicate therapy detection (shared drug class, FR-TERM-011)
- Drug-condition contraindication checking (FR-TERM-012)
Out of scope: Clinical workflow logic; patient-level medication history; prescribing rules beyond CDS signals; FHIR resource persistence (terminology-service does not store clinical resources).
5. Supported Terminology Systems
| System | URI | Use case |
|---|---|---|
| LOINC | http://loinc.org | Lab tests, vitals observations |
| SNOMED CT | http://snomed.info/sct | Diagnoses, findings, body sites, procedures |
| RxNorm | http://www.nlm.nih.gov/research/umls/rxnorm | Medication codes, drug classes |
| ICD-10-CM | http://hl7.org/fhir/sid/icd-10-cm | Diagnoses (Afghanistan adaptation) |
| Custom/tenant | urn:ghasi:tenant:{tenantId} | Site-specific coded values |
6. FHIR Operations Provided
| Operation | Path | Standard |
|---|---|---|
$lookup | GET /fhir/R4/CodeSystem/$lookup | FHIR R4 TerminologyCapabilities |
$validate-code | POST /fhir/R4/CodeSystem/$validate-code | FHIR R4 |
$expand | GET /fhir/R4/ValueSet/$expand | FHIR R4 |
$translate | POST /fhir/R4/ConceptMap/$translate | FHIR R4 |
FHIR operations are also proxied from interop-service's /fhir/R4/ base URL. Terminology-service itself serves these operations on its own base path and is the source of truth.
7. Context Diagram
8. Upstream / Downstream Dependencies
| Direction | Service | Interaction |
|---|---|---|
| Consumed by | medication-service | Drug class lookup, interaction/duplicate/contraindication CDS |
| Consumed by | laboratory-service | LOINC code lookup for result coding |
| Consumed by | orders-service | Concept search for order coding |
| Consumed by | patient-chart-service | SNOMED/ICD-10 lookup for problem list |
| Consumed by | interop-service | FHIR terminology op proxy |
| Consumed by | immunizations-service | Vaccine code lookup (CVX via SNOMED) |
| Publishes events to | NATS JetStream | TERMINOLOGY.concept.*, TERMINOLOGY.dataset.updated |
| No outbound service calls | — | Terminology-service is a leaf service in the dependency graph |
9. Licensing Notes
- LOINC: Free with registration — Regenstrief Institute license. CSV download from loinc.org.
- SNOMED CT: Requires SNOMED International NRC/affiliate license per country. Afghanistan status: MoPH has affiliate access.
- RxNorm: NLM public domain for US drug codes. International drug codes require separate licensed database.
- ICD-10-CM: US-licensed release. Afghanistan adaptation layers maintained by MoPH.
- Drug interaction data: Requires a licensed clinical knowledge source (Multum, DrugBank, or NDF-RT) for production use. Must not bundle copyrighted data in the source repository.
Terminology data is never committed to the repository. Licensed data files are loaded via the ETL pipeline into the PostgreSQL concepts table at deployment time.