id: TEDY.01 template: tool-feature module: tedy state: Proposed traces-from: [] # TODO: link terminology-editor user stories source-refs:

reference-editor/app/src/app/resources/code-system
reference-editor/app/src/app/resources/_lib/code-system/model/code-system.ts
terminology-server (/ts/code-systems)
helex-tx/libs/tedy/src/lib/client/codeSystemClient.ts
helex-tx/libs/tedy/src/lib/client/conceptClient.ts
helex-tx/libs/tedy/src/lib/types/codeSystem.ts author: TEDY bootstrap created: 2026-08-08 updated: 2026-08-08

TEDY.01 – Code System (Common Spec)

Description

Common specification for Code System management in TEDY — browse, view, and author FHIR CodeSystems over terminology-server (/ts/code-systems). This root spec owns the shared vocabulary, data model, value sets, FHIR mapping, privileges, common API surface, and navigation so the child (screen) specs don’t duplicate them.

terminology-server owns the persistence + FHIR model; TEDY is the React client. Derived via spec-authoring.md (Step-1 dev-tx.example scan, Step-2 reference-editor + terminology-server reconcile).

Child specs:

Glossary Terms

Term (canonical)	Meaning
Code System	A FHIR CodeSystem — a managed set of concepts (codes) with designations, versions, properties.
Concept	A single code within a Code System (its content).
Version	A `CodeSystemVersion` with a publication status (draft/active/retired) + release date.
Designation	A concept’s localized display/definition (`designationType` = display/definition, per language).
Publisher	`CodeSystem.publisher` — resolved via the `publisher` value set when it is a code, else free text.
Space	A reference-platform authoring workspace a resource belongs to.
Content mode	`CodeSystem.content` — complete / supplement / fragment / example / not-present.

Business Feature Sitemap

flowchart LR
    US["(TODO) US: manage code systems"] --> ROOT[TEDY.01]
    ROOT --> LST[TEDY.01.1 List]
    ROOT --> CRT[TEDY.01.2 Add]
    ROOT --> VIEW[TEDY.01.3 View]
    LST -->|Add code system| CRT
    LST -->|row / ID| VIEW
    CRT -->|save| VIEW

Data Model

Shared model for list / create / view. terminology-server owns the tables; TEDY consumes the JSON envelopes.

Entity / Resource	the reference platform API	FHIR resource	Notes
CodeSystem	`/ts/code-systems`	CodeSystem	list + detail; `lastVersion` decorated
CodeSystemVersion	`/ts/code-systems/{id}/versions`	CodeSystem.version	status ∈ draft/active/retired
CodeSystemConcept	`/ts/code-systems/{id}/concepts`	CodeSystem.concept	content; display from designations
List envelope	n/a	n/a	`{ data: [...], meta: { total, offset } }`
Single-resource envelope	n/a	n/a	resource root fields

Shared CodeSystem fields

Field	Type	Cardinality	Rule
`id`	string	1..1	immutable identity (the code-system id)
`uri`	string	0..1	canonical URL; unique
`name`	string	0..1	machine name
`title`	LocalizedName	0..1	multilingual display
`description`	LocalizedName	0..1
`publisher`	string	0..1	code from `publisher` VS or free text
`content`	code	0..1	codesystem-content-mode
`caseSensitive`	code	0..1	cs / ci
`baseCodeSystem`	string	0..1	for supplements
`versions` / `lastVersion`	CodeSystemVersion[]	0..*	version + status + releaseDate + conceptsTotal
`concepts`	CodeSystemConcept[]	0..*	code + versions[].designations[]

Used value sets (resolved via @helex/tx)

Field	ValueSet	Canonical URL	Binding
`publisher`	publisher	`https://tx.example/fhir/ValueSet/publisher`	extensible
version `status`	publication-status	`http://hl7.org/fhir/ValueSet/publication-status`	required
`content`	codesystem-content-mode	`http://hl7.org/fhir/ValueSet/codesystem-content-mode`	required

FHIR Mapping (Common)

Internal field	FHIR R5 path	Mapping	Notes
`id`	`CodeSystem.id`	direct
`uri`	`CodeSystem.url`	direct
`name`	`CodeSystem.name`	direct
`title`	`CodeSystem.title`	transform	LocalizedName → language-resolved title
`publisher`	`CodeSystem.publisher`	direct
`content`	`CodeSystem.content`	direct
`caseSensitive`	`CodeSystem.caseSensitive`	transform	cs/ci → boolean
`lastVersion.version`	`CodeSystem.version`	direct
`concepts[]`	`CodeSystem.concept[]`	transform	designations → concept.display + designation

Common Rules

Phase-0 TEDY is read-only (browse/view). Authoring (create/edit) writes via POST /ts/code-systems/transaction (child TEDY.01.2 / future edit).
Concept display resolves from versions[].designations[] where designationType='display' (match language → preferred → first), fallback to the code.
Publisher display resolves via the publisher value set (@helex/tx), fallback to the raw value when free text.
Value-set-backed selects use TxConceptSelect(url=…) (see spec-authoring.md; dev proxies /api/tx/$expand→the reference platform FHIR).

Shared Privileges

Action	Privilege
View / browse	authenticated (dev: guest via the reference platform `yupi`)
Create / edit / delete / versions / concepts	`CodeSystem.write` (the reference platform `{id}.CodeSystem.write`)

Common API Surface

Method	Path	Privilege	Description
GET	`/ts/code-systems`	read	list (params: textContains, publisher, versionStatus, spaceId, content, lastVersionDecorated, lang)
GET	`/ts/code-systems/{id}`	read	load one (`?decorate=true`)
GET	`/ts/code-systems/{id}/versions`	read	versions
GET	`/ts/code-systems/{id}/concepts`	read	concepts (params: textContains, codeContains, displayLanguage)
POST	`/ts/code-systems/transaction`	write	create/update (authoring)
GET	`/spaces`	read	spaces (for the Space filter)
GET	`/fhir/ValueSet/$expand?url=…`	read	value-set expansion (publisher/status/content)

All TEDY calls go through @helex/tedy’s txApi (/txapi → dev-tx.example /api).

/tedy/code-systems — list (TEDY.01.1)
/tedy/code-systems/new — create (TEDY.01.2, pending)
/tedy/code-systems/{id} — view (TEDY.01.3)

(Standalone Router basename="/tedy"; menu routes are basename-relative — see spec-authoring/dev notes.)

Non-functional Requirements

Requirement	Target
List load	< 2s; server-side pagination (20/page); no eager concept load
Detail + concepts load	< 2s; concepts paged (20/page)
Search debounce	~400ms

Business Tests

List, view, and (future) create all operate over /ts/code-systems* with the shared envelope.
Publisher/status/content render via their value sets; concept display via designations.
Write actions require CodeSystem.write; read is open on the guest dev server.

Traces

traces-from: TODO user stories
children: TEDY.01.1, TEDY.01.2, TEDY.01.3

helex-tx — terminology suite docs