Terminology Service — Domain Model

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

---

1. Aggregate: Concept

Root entity. A Concept represents a single coded clinical term within a terminology system (LOINC, SNOMED CT, RxNorm, ICD-10-CM, or a tenant-scoped custom system). It is the fundamental unit of meaning throughout the platform.

Attributes

Attribute	Type	Notes
id	string	ULID, prefix CON_
system	string	URI of the code system (e.g., http://loinc.org)
code	string	The code value within the system
display	string	Human-readable name
definition	string | null	Full definition text
active	boolean	False for retired/deprecated codes
tenantId	string | null	null = global (all tenants); non-null = tenant-scoped
version	number	Optimistic lock
createdAt	Date	Immutable
updatedAt	Date	Updated on deactivation or display correction

Invariants

• (system, code) is unique when tenantId IS NULL (global concepts)
• (tenantId, system, code) is unique when tenantId IS NOT NULL (tenant-scoped)
• Only platform admins may create/update/deactivate global concepts
• Tenant admins may only manage concepts scoped to their own tenant
• Only active = true concepts are returned by search, lookup, expand, and validate operations (BR-TERM-001)
• code and system are immutable after creation; only display, definition, and active may be updated

State Machine

active = true → active = false (deactivation only; no re-activation via API)

Deactivation is a one-way transition. Concepts are never deleted; deactivated concepts are retained for audit and backward reference.

---

2. Aggregate: DrugInteraction

Encodes a pairwise drug-drug interaction relationship between two RxNorm drug codes.

Attributes

Attribute	Type	Notes
id	string	ULID, prefix DI_
drug1Code	string	RxNorm code
drug2Code	string	RxNorm code
severity	InteractionSeverity	CONTRAINDICATED | HIGH | MODERATE | LOW
description	string	Clinical explanation of the interaction
source	string	Knowledge source identifier (e.g., multum, drugbank)
active	boolean	Allows disabling specific interaction records
version	number	Optimistic lock
createdAt	Date	Immutable

Invariants

• The pair (drug1Code, drug2Code) is symmetric in search (querying A+B returns interactions for A-B and B-A)
• severity must be one of: CONTRAINDICATED, HIGH, MODERATE, LOW (ordered highest to lowest risk)
• source must reference a known licensed data source identifier (validated at import time)
• Pairwise interactions with active = false are excluded from interaction-check responses

---

3. Read Model: DrugClass

A read-only reference table mapping RxNorm drug codes to their pharmacological class(es).

Attributes

Attribute	Type	Notes
id	string	ULID, prefix DC_
rxnormCode	string	RxNorm code
className	string	Drug class name (e.g., beta-blocker, ACE inhibitor)
classSystem	string	Source classification system (e.g., NDF-RT, MED-RT)
active	boolean	—

Used by FR-TERM-005 (drug class lookup) and FR-TERM-011 (duplicate therapy detection: two drugs sharing at least one className are flagged as potential duplicates).

---

4. Read Model: DrugContraindication

A read-only reference table mapping RxNorm drug codes to contraindicated ICD-10-CM conditions.

Attributes

Attribute	Type	Notes
id	string	ULID, prefix DCI_
rxnormCode	string	RxNorm code of the drug
icd10Code	string	ICD-10-CM code of the contraindicated condition
severity	ContraindicationSeverity	ABSOLUTE | RELATIVE
description	string	Clinical rationale
active	boolean	—

Used by FR-TERM-012 (drug-condition contraindication checks).

---

5. Read Model: ValueSet

A named collection of concept codes, used for FHIR ValueSet/$expand operations.

Attributes

Attribute	Type	Notes
id	string	ULID, prefix VS_
url	string	Canonical ValueSet URL
name	string	Human-readable name
status	string	active | retired
tenantId	string | null	Scope; null = global
conceptIncludes	ValueSetInclude[]	{system, concepts[]} or {system, filter}
version	string	Semantic version

---

6. Domain Events

Event	Trigger	Payload summary
TerminologyConcept.Created	Admin creates a concept	conceptId, system, code, display, tenantId
TerminologyConcept.Deactivated	Admin deactivates a concept	conceptId, system, code, reason
TerminologyDataset.Updated	Bulk terminology import completes	importJobId, systemsUpdated[], conceptsAdded, conceptsDeactivated

---

7. Value Objects

Value Object	Description
CodingSystem	Validated URI for a known terminology system
ConceptCode	Trimmed, non-empty string; max 50 chars
InteractionSeverity	Enum: CONTRAINDICATED | HIGH | MODERATE | LOW
ContraindicationSeverity	Enum: ABSOLUTE | RELATIVE

---

8. Ubiquitous Language

Term	Definition
Concept	A single coded term with a system, code, display, and active flag
Global concept	A concept with tenantId = null; visible to all tenants
Tenant concept	A concept scoped to a specific tenant; not visible to other tenants
Active concept	active = true; returned by all public query operations
Deactivated concept	active = false; retired from use but retained for audit
ValueSet expansion	The resolved list of active concept codes matching a ValueSet URL
Drug class	A pharmacological classification for a drug (e.g., beta-blocker)
Drug interaction	A pairwise CDS signal between two drug codes with a severity level
Duplicate therapy	Two or more prescribed drugs sharing at least one drug class
Contraindication	A drug-condition pair where the drug is unsafe given the patient's condition
LOINC	Logical Observation Identifiers Names and Codes — standard for lab tests and observations
SNOMED CT	Systematized Nomenclature of Medicine — Clinical Terms
RxNorm	NLM standard for medication codes
ICD-10-CM	International Classification of Diseases, 10th revision
$lookup	FHIR operation: exact code lookup returning display and status
$validate-code	FHIR operation: confirms a code is active in a system
$expand	FHIR operation: returns the concept list for a ValueSet URL
$translate	FHIR operation: maps a code from one system to another via ConceptMap
ETL pipeline	The data operations process that loads licensed terminology files into the database
Offline snapshot	A pre-loaded, self-contained terminology database included in facility-node deployments