Terminology Service — Epics
Service: terminology-service Epic prefix: TERM-EPIC Last updated: 2026-04-18
Epics
TERM-EPIC-01 — Concept Search, Lookup, and Validation
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Core terminology query surface: search, lookup, validate |
| Status | In Progress |
| Priority | Must |
| Labels | service:terminology-service, domain:terminology, slice:S0 |
| Components | concept-query-api, concept-repository, redis-cache |
| Fix version | M0 |
| FR references | FR-TERM-001, FR-TERM-002, FR-TERM-003 |
| Legacy FR refs | FR-TERM-001, FR-TERM-002, FR-TERM-003 (preserved from _sources/terminology/SPEC.md) |
| Dependencies | (none — foundational) |
| Rollup status | Implemented |
Business outcome: All clinical services can look up, search, and validate coded clinical terms from a single, consistent terminology authority, eliminating duplicated coding logic across the platform.
Description: Delivers the full-text concept search endpoint, exact system+code lookup (with Redis caching), and active/inactive code validation. These three operations form the foundational query surface used by every clinical module. All endpoints enforce tenant scope (global + own-tenant concepts only) and return only active concepts. p95 latency target: ≤ 200 ms for search, ≤ 100 ms for lookup/validate under warm cache.
Stories: TERM-US-001, TERM-US-002, TERM-US-003
TERM-EPIC-02 — ValueSet Expansion Services
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Canonical ValueSet URL expansion for downstream workflow decision logic |
| Status | In Progress |
| Priority | Must |
| Labels | service:terminology-service, domain:terminology, slice:S0 |
| Components | value-set-api, value-set-repository |
| Fix version | M0 |
| FR references | FR-TERM-004 |
| Legacy FR refs | FR-TERM-004 |
| Dependencies | TERM-EPIC-01 |
| Rollup status | Implemented |
Business outcome: Order sets, result interpretation workflows, and decision support rules can reliably expand standard FHIR value sets into their constituent active concepts.
Description:
Provides the $expand operation: given a canonical ValueSet URL, return all active member concepts. Expansion results are cached in Redis (5-min TTL) to handle the high call volume from orders and clinical decision workflows. Expansion respects the MAX_EXPANSION_SIZE limit (default 500).
Stories: TERM-US-004
TERM-EPIC-03 — Medication Safety Intelligence (CDS)
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Drug class lookup, drug-drug interaction checking, duplicate therapy, contraindication |
| Status | In Progress |
| Priority | Must |
| Labels | service:terminology-service, domain:terminology, slice:S0 |
| Components | cds-api, drug-interaction-repository, drug-class-repository |
| Fix version | M0 |
| FR references | FR-TERM-005, FR-TERM-006, FR-TERM-011, FR-TERM-012 |
| Legacy FR refs | FR-TERM-005, FR-TERM-006, FR-TERM-011, FR-TERM-012 |
| Dependencies | Drug interaction licensed data loaded via ETL |
| Rollup status | Implemented |
Business outcome: The medication-service and prescribing workflows can programmatically identify unsafe drug combinations, duplicate therapies, and contraindicated drug-condition pairs, reducing adverse drug events.
Description: Covers four CDS endpoints: drug class lookup by RxNorm code (supports class-based duplicate detection), pairwise drug-drug interaction check with severity output, duplicate therapy detection (shared drug class), and drug-condition contraindication check by RxNorm + ICD-10 code list. All require the licensed drug interaction knowledge base to be loaded via ETL.
Stories: TERM-US-005, TERM-US-006, TERM-US-007, TERM-US-008
TERM-EPIC-04 — Tenant Governance, Admin CRUD, and Events
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Concept lifecycle management, tenant custom concepts, bulk import, event publication |
| Status | In Progress |
| Priority | Must |
| Labels | service:terminology-service, domain:terminology, slice:S0 |
| Components | admin-api, import-pipeline, outbox-relay |
| Fix version | M0 |
| FR references | FR-TERM-007, FR-TERM-008, FR-TERM-009 |
| Legacy FR refs | FR-TERM-007, FR-TERM-008, FR-TERM-009 |
| Dependencies | TERM-EPIC-01 |
| Rollup status | Implemented |
Business outcome: Platform operators and tenant administrators can safely govern terminology data — adding facility-specific codes, importing licensed data, and ensuring downstream consumers receive change notifications.
Description:
Covers tenant-scoped custom concept governance (tenant admin can create/deactivate concepts scoped to their tenant only), global concept management (platform admin only), optional CSV bulk import (controlled by IMPORT_ENABLED flag), and mutation event publication (TERMINOLOGY.concept.created, .deactivated, TERMINOLOGY.dataset.updated). All mutations follow the outbox pattern.
Stories: TERM-US-009, TERM-US-010, TERM-US-011, TERM-US-018
TERM-EPIC-05 — Security and Operational NFR Baseline
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Authentication, entitlement controls, latency/capacity SLOs, licensing safeguards |
| Status | In Progress |
| Priority | Must |
| Labels | service:terminology-service, domain:terminology, slice:S0 |
| Components | auth-guards, health-checks, observability |
| Fix version | M0 |
| FR references | FR-TERM-010 |
| Legacy FR refs | FR-TERM-010, NFR-TERM-001, NFR-TERM-002, NFR-TERM-003 |
| Dependencies | Keycloak realm |
| Rollup status | Partial |
Business outcome: The terminology service operates within defined SLOs and enforces access control boundaries, providing measurable compliance evidence for the platform security posture.
Description: JWT-based authentication on all public routes; optional internal shared-secret on internal routes; role-based CRUD guards for admin operations; SLO-aligned latency evidence via k6 performance tests; capacity test with ≥ 300k concept dataset; licensed data handling controls (no data in repo). Health + readiness endpoint exposes DB and Redis dependency status.
Stories: TERM-US-015, TERM-US-016, TERM-US-017, TERM-US-019
TERM-ENH-EPIC-01 — FHIR Interoperability Completion
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | TerminologyCapabilities metadata, ConceptMap $translate, version-aware operations |
| Status | To Do |
| Priority | Should |
| Labels | service:terminology-service, domain:terminology, slice:S1 |
| Components | fhir-operations, concept-map-api |
| Fix version | M2 |
| FR references | FR-TERM-ENH-001, FR-TERM-ENH-002, FR-TERM-ENH-009 |
| Legacy FR refs | FR-TERM-ENH-001, FR-TERM-ENH-002, FR-TERM-ENH-009 |
| Dependencies | TERM-EPIC-01 |
| Rollup status | Not implemented |
Business outcome: External FHIR clients (including EHR products and interop-service) can discover terminology capabilities via standards-based metadata and perform code system translations through the platform's canonical terminology server.
Description:
Adds GET /fhir/R4/metadata returning a TerminologyCapabilities resource; implements POST /fhir/R4/ConceptMap/$translate for cross-system code mapping; adds version-aware lookup and validation with explicit CodeSystem version parameter. Enables full FHIR R4 terminology server conformance claim.
Stories: TERM-ENH-US-001, TERM-ENH-US-002, TERM-ENH-US-003
TERM-ENH-EPIC-02 — High-Throughput CDS Query Controls
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Batch lookup, severity-filtered interactions and contraindications |
| Status | To Do |
| Priority | Should |
| Labels | service:terminology-service, domain:terminology, slice:S1 |
| Components | cds-api, batch-api |
| Fix version | M2 |
| FR references | FR-TERM-ENH-012, FR-TERM-ENH-014, FR-TERM-ENH-015 |
| Legacy FR refs | FR-TERM-ENH-012, FR-TERM-ENH-014, FR-TERM-ENH-015 |
| Dependencies | TERM-EPIC-03 |
| Rollup status | Not implemented |
Business outcome: High-throughput prescribing and clinical decision support workflows can resolve many codes in a single round trip and filter CDS alerts to clinically relevant severity levels.
Description:
Adds batch concept lookup (up to configurable max in a single POST), minimumSeverity filter on drug-drug interaction endpoint (suppresses LOW/MODERATE when not clinically relevant), and minimumSeverity filter on drug-condition contraindication endpoint. Improves network efficiency for bulk callers (e.g., medication reconciliation, order entry).
Stories: TERM-ENH-US-004, TERM-ENH-US-005, TERM-ENH-US-006
TERM-ENH-EPIC-03 — Tenant Protection and Operability
| Field | Value |
|---|---|
| Issue type | Epic |
| Summary | Per-tenant rate limiting and health/readiness endpoint diagnostics |
| Status | To Do |
| Priority | Could |
| Labels | service:terminology-service, domain:terminology, slice:S2 |
| Components | rate-limiting, health-checks |
| Fix version | M3 |
| FR references | (none — NFR) |
| Legacy FR refs | NFR-TERM-ENH-001, NFR-TERM-ENH-003 |
| Dependencies | TERM-EPIC-05 |
| Rollup status | Not implemented |
Business outcome: A single high-volume tenant cannot degrade terminology service performance for all other tenants, and dependency failures are surfaced in health endpoints for automated alerting.
Description:
Per-tenant query rate limiting (configurable quota per tenant per minute); HTTP 429 responses when quota exceeded; per-tenant throttle metrics in Prometheus. Enhanced /health endpoint exposes per-dependency status (DB, Redis, NATS) with latency readings for SRE diagnostic use.
Stories: TERM-ENH-US-007, TERM-ENH-US-008