Architecture decision: data model for storing user-generated post-coordinated concepts (ICD-11 / SNOMED)

[jamlung-ri]

Background

ICD-11 and SNOMED support post-coordination workflows, where users create pre-coordinated expressions by combining STEM codes and extension codes. Currently, the AI agent writes these new expressions into the main ICD-11 WHO repo (or a lookup repo), but there is no clear architectural decision on where user-generated post-coordinated concepts should live or how they should be modeled.

This is a design discussion ticket to evaluate the options and reach a decision before building further.

Problem

• Post-coordinated terms are user/org-specific and should not go into the official WHO release
• ICD-11 extension code ordering can vary (producing semantically equivalent but syntactically different strings), so de-duplication and canonical representation are unresolved
• The current setup defaults to writing into the wrong place when lookup config is missing

Options to Evaluate

Option 1: Don't create new concepts
When opening the candidate popover/modal, simply resolve each component (stem, extension, etc.) by pointing directly to the main ICD-11 source. No new concepts are created or stored — components are resolved on the fly.

Option 2: Create them in an alternative lookup source
Similar to what we currently have — post-coordinated expressions are stored in a separate lookup/preview repo owned by the user/org, used only for lookup and display purposes and not as part of the main terminology.

Option 3: Build a more robust storage layer
Fully model post-coordination inside OCL — create first-class concept entities for post-coordinated expressions with proper mappings to their component codes. Note: this feels too ICD-11-specific and it's unclear this should be OCL's responsibility.

Next Steps

• Schedule an architectural discussion with Andy, Jonathan, Sunny, and Filipe
• Document the decision and update the OCL Mapper and AI Agent behavior accordingly

[filiperochalopes]

If we’re going to display concepts as results of OCL Mapper automatch flow — and each concept can have multiple related candidates — then I think only options 2 and 3 are viable. Treating WHO-ICD-11 concepts as only stem codes isn’t enough, because a single stem can still produce many related candidates with different extension codes. That situation would still occur under option 1, unless:

Related to #2338 #2380

[filiperochalopes]

Populated Private WHO-ICD-11 source for reference: https://app.openconceptlab.org/#/orgs/OpenMRS-OCL-Squad/sources/ICD-11-WHO/