Teagle (tx-vision) — terminology aggregator / eXplorer 🦅

Teagle is the eagle-eyed terminology aggregator — it routes and merges FHIR terminology operations across multiple registered upstream servers, and can serve editable in-process content. It is the HELEX-platform successor to the reference Terminology eXplorer (tx-router / tx-viewer), rebuilt on Flint instead of fhirest/commons-fhir-proxy: every per-source FHIR operation runs through the Flint engine.

Module: modules/teagle/backend (package org.helex.tx.teagle, TeagleApplication, :18650), stateless (no DB), depends only on org.helex.tx:tx-fhir. Frontend: React + @helex/ui, laid out like the reference eXplorer.

Server registry

An ecosystem.json-style config (tx-ecosystem IG shape; ${VAR:-default} env interpolation, blank-target HTTP servers dropped as inactive) materialises into TerminologySources of three kinds:

• http — an external FHIR terminology server; operations ride Flint’s FhirUpstreamDelegate.
• local — content served in-process by the Flint kernel.
• in-memory editable (new — the reference had no writable server) — over Flint’s MutableResourceStore; PUT/DELETE /fhir/{Type}/{id} author content into the running aggregator, immediately expandable. Ideal for tests and demos.

Routing decision (config order; exclusions before authoritative match; exact / glob / regex / type-collection / version-pinned patterns): no match ⇒ Teagle itself (Flint kernel, fail-closed). Backed by a RoutingCatalog (explicit-over-wildcard, active-over-retired precedence, id--version resolution).

Operations

• Multi-source $expand — resolve (inline / store / implicit / remote-owned canonical) → per-system fan-out (local groups on the Flint kernel; remote groups on the owning server) → system|code dedup merge → imports (intersection within an include, union across) → post-merge text filter (also forwarded to sub-expansions) → offset/count paging with a true total. A fully-local compose takes a Flint fast-path so aggregation never degrades conformance semantics.
• ?vs (all-codes implicit VS) is synthesised locally (404 on unknown CS — never an empty 200); ?fhir_vs (ECL / isa / refset) routes through Flint’s SNOMED provider (version→branch), with the owning registry server as fallback — an improvement over the reference explorer, which blind-forwarded ?fhir_vs.
• Registry-aware $lookup / $validate-code dispatch, and an aggregated /fhir/metadata (+?mode=terminology with per-CodeSystem target-server annotations). /api/servers lists the registry.

Request model (inherited from the eXplorer)

Content-negotiated reads (same URL, Accept selects UI vs FHIR JSON/XML); versioned resources use | in FHIR canonicals and -- internally (/fhir/CodeSystem/foo--1.0.6). See the reference terminology-explorer/docs/routing-specification.md for the full URL/versioning/lifecycle detail Teagle preserves.

Teagle vs FIS

FIS is the platform-wide FHIR gateway (multi-module fan-out via fhir-route-config.yml); Teagle is a terminology-domain aggregator whose distinct value is external SNOMED/UCUM reach and the editable in-memory server. They coexist — Teagle can be registered as a FIS target.

Run

./scripts/run_backend.sh teagle       # aggregator on :18650
./scripts/run_frontend.sh teagle      # React UI (once the frontend lands), proxying to :18650