Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

TEDY.08 — Servers (terminology / FHIR server registry)

State: Proposed (built: list [search + filter + Add] · create · TxResourceBar detail [Summary with 5 authoritative widgets · Metadata full form + check-connection · Resources] · authoritative editor). Ecosystem export/import & remote resource listing phased. Template: tool-feature. Prefix: TEDY.

Feature grouping

Root spec for the Servers family (a “Management” section resource). Sits alongside TEDY.09 Ecosystems (which groups servers) and TEDY.07 Spaces.

Overview

A registry of external terminology / FHIR servers. Each server carries connection + auth config, declared FHIR versions, capability flags, five “authoritative resources” collections (canonical patterns the server owns) and a currentInstallation flag for the local baseline. Served off /servers (NOT /ts/*); numeric id.

Data model (libs/tedy/src/lib/types/server.ts)

Server: id:number, code, names:LocalizedName, rootUrl, kind: ('terminology'|'fhir'|'snomed')[], active, currentInstallation, accessInfo, usage[], supportedOperations[], strategy (inline|cached|local), cachePeriodHours, fhirVersions:{version,url}[], headers: ServerHeader[], authConfig: ServerAuthConfig, capability flags open/token/oauthFlag/smartFlag/certFlag, exclusions[], and the five authoritative collections authoritative / authoritativeValuesets / authoritativeConceptmaps / authoritativeStructuredefinitions / authoritativeStructuremaps (AuthoritativeResource[]).

  • ServerHeader { key?; value?; _masked? }, ServerAuthConfig { authType: none|basic|oauth2|apikey; accessTokenUrl?; clientId?; clientSecret?; scope?; _masked? }.
  • AuthoritativeResource { url?; status?; version?; name?; _inclusive? }.
  • ServerConnectionCheckResult { success; statusCode?; url?; durationMs?; software?; softwareVersion?; fhirVersion?; error? }.
  • SERVER_AUTHORITATIVE_FIELD: Record<ServerResourceType, keyof Server> maps each type → its collection field.

Secrets (authConfig.clientSecret, Authorization header values) are masked server-side; the edit form uses the _masked = “null-means-keep-persisted” convention.

REST API (base /servers)

  • GET /servers?{params} → SearchResult<Server>; params incl. textContains, kinds, currentInstallation (public view when the caller lacks Server.write).
  • GET /servers/{id} → Server (write-privileged load-for-edit); POST / PUT → upsert.
  • GET /servers/{id}/check-connection → ServerConnectionCheckResult.
  • GET /servers/{id}/resources/{type} → AuthoritativeResource[] (local for current-installation; live-paged remote otherwise).
  • POST /servers/{id}/authoritative/{type}/preview → matching resources.
  • GET /servers/export/ecosystem?download / POST /servers/import/ecosystem → FHIR-ecosystem interchange (phased).

Screens (all built unless noted)

  • List — Code · Name · Kind · Active · Current installation; search → textContains; filter panel (kind, current-installation); Add (write-gated) → create.
  • Create (ServerCreate) — code, name, kind, FHIR version + URL, active (POST). Full field set edited afterwards on Metadata.
  • Summary — Server info card + FHIR Ecosystem card, then five authoritative-resource widgets (ServerAuthoritativeListWidget): each lists the server’s authoritative* entries (url · version · status), with Add/Change → the authoritative editor and Delete (removes + re-saves the server).
  • Metadata — read-only view + inline edit of the full field set: code, name, kind, FHIR versions, strategy, cache, usage, supported operations, access info, active/current, custom headers table, auth-config block (authType + accessTokenUrl/clientId/clientSecret/scope, secret-masked), capability flags (open/token/OAuth/SMART/Cert). Card footer has Check connection → colored result tag (tooltip = probed URL) + success/failure toast.
  • Resources tab — a classical ResourceList with the filter panel on the right (resource-type multiselect, Code Systems preselected) + search over GET /servers/{id}/resources/{type}. Each row has two actions: Open in Terminology eXplorer (web viewer at TX_VIEWER_URL, e.g. https://tx.helex.dev/fhir/{Type}/{name}) and Open external FHIR resource ({server.rootUrl}/{Type}/{name}). TX_VIEWER_URL is configured via VITE_TX_VIEWER_URL (config/tx.ts; default https://tx.helex.dev).
  • Authoritative editor (/servers/:id/authoritative/:type) — add-by-URL, Include/URL/Version/Status rows, Preview (POST …/preview), Save (writes the mapped collection).

Routes & nav

/servers (list), /servers/new (create), /servers/:id → TxResourceBar tabs (summary/details/resources), /servers/:id/authoritative/:type (editor). Nav: Management → Servers (CloudServerOutlined).

Privileges

Two families coexist: *.Server.read / *.Server.write (backend @Authorized, menu, list Add) and *.Space.read / {id}.Space.write (route guards + in-page edit affordances). Gate with usePrivileged().

Built artefacts

  • Data layer: types/server.ts, client/serverClient.ts (searchServers, loadServer, saveServer, loadServerResources, checkServerConnection, previewAuthoritative), hooks/useServers.ts (useServers, useServer, serverKeys).
  • Screens: pages/ServerList.tsx, pages/server/{ServerCreate,ServerResourceLayout,ServerSummary,ServerMetadata,ServerResourcesTab,ServerAuthoritativeEdit}.tsx, pages/server/widgets/ServerAuthoritativeListWidget.tsx. TxResourceBar extended with terminology-server (no version chip) + a resources mode.

Phased (documented, not built)

  • Ecosystem export/import actions on the list (/servers/export|import/ecosystem).
  • Remote resource listing niceties (local-vs-remote link routing, $summary-aware links) in the Resources tab.

See open questions in TEDY-new-modules-open-questions.md.