Terminology Service — Service Readiness

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · docs/standards/DEFINITION_OF_DONE.md

1. Readiness Gate Checklist

Architecture & Design

• All 17 service docs populated (no stubs remaining)
• DOMAIN_MODEL.md reviewed; Concept and CDS aggregate invariants confirmed
• API_CONTRACTS.md finalized; OpenAPI spec generated from controllers
• SECURITY_MODEL.md reviewed; licensed data handling policy confirmed
• FHIR operations surface reviewed by interop team

Implementation

• NestJS service scaffolded per hexagonal architecture
• Drizzle ORM schema matches DATA_MODEL.md
• PostgreSQL migrations checked in under src/infrastructure/migrations/
• RLS policy applied to concepts table
• Outbox relay worker implemented and tested
• Import endpoint guarded by IMPORT_ENABLED flag
• Redis cache implemented for lookup, validate, expand operations
• Cache key jitter added (±5% TTL) to prevent stampede

Data / ETL

• ETL Kubernetes Jobs defined for LOINC, SNOMED, RxNorm, ICD-10
• ETL runs successfully in staging environment
• Concept counts verified post-import (minimum thresholds met)
• Drug interaction data loaded and spot-checked
• Standard value sets seeded (pnpm db:seed:valuesets)
• Readiness probe checks terminology_data: loaded

Testing

• Unit test coverage ≥ 85%
• Integration test coverage ≥ 80%
• tenant-isolation.spec.ts green (tenant A cannot see tenant B custom concepts)
• outbox.spec.ts green
• inbox.spec.ts green (if applicable)
• Cache hit / miss behavior tested
• CDS endpoint tests: interaction, duplicate therapy, contraindication
• FHIR operation tests: $lookup, $validate-code, $expand, $translate

Security

• JWT enforcement verified on all /v1/terminology/* and /fhir/R4/* routes
• IMPORT_ENABLED=false behavior tested (returns 405)
• Tenant RLS isolation test green
• No licensed data files present in repository (audit git log)
• Internal route shared-secret enforcement tested (if INTERNAL_TOKEN set)

Observability

• OpenTelemetry traces emitting all spans per OBSERVABILITY.md
• Prometheus metrics scraping active
• Terminology Overview dashboard deployed in Grafana
• All P1 and P2 alerts configured in Alertmanager
• ETL last-success-age metric emitting

Operations

• GET /health returns dependency status for DB and Redis
• Kubernetes deployment manifests reviewed
• HPA configured
• Environment variables documented in .env.example
• Offline snapshot bundle generated and tested

---

2. Go/No-Go Criteria

Category	Must-pass	Should-pass
ETL	Concept count > 100k after import	All 5 systems loaded
Testing	tenant-isolation, outbox, CDS endpoint tests	FHIR $translate test
Security	Licensed data not in repo, JWT enforcement active	Internal token test
Observability	Latency SLO alerts active, ETL age metric emitting	Dashboard published