# chb/py-umls architecture

> Architecture diagram of the GitHub repository chb/py-umls, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chb/py-umls
- Repository: https://github.com/chb/py-umls

## Overview

1. This repository is a small Python 3 toolkit for working with medical vocabularies from UMLS, SNOMED CT, and RxNorm. Its core model is: download official terminology releases, import them into a local SQLite 3 database, then query them through lightweight Python lookup classes.

2. The main user-facing entry points are the three scripts `umls.py`, `snomed.py`, and `rxnorm.py`. According to the README, each can be run directly from the shell, prompts the user to install the relevant data, and then demonstrates a simple code-to-meaning lookup.

3. The data layer is local and file-based rather than network-service based. The repository assumes each terminology is stored in a SQLite database created from the official source files. The `sqlite.py` module is likely the shared database access layer, while `csvimporter.py` appears to support bulk import of source CSV/flat files into SQLite tables.

4. The import/download workflow is split out from lookup logic. In the file tree, `databases/rxnorm.sh` and `databases/umls.sh` are shell scripts for acquiring and preparing the vocabulary datasets, while `rxnorm_download.py` and `rxnorm_link_run.py`/`rxnorm_link_run.sh` look like helper scripts for fetching or transforming RxNorm-specific inputs and building derived link data.

5. Each vocabulary has its own module boundary: `umls.py`, `snomed.py`, and `rxnorm.py`. The README says each exposes an `XYLookup` class, so the architecture is centered on per-terminology lookup objects with a common usage pattern, even if the underlying schemas differ.

6. There are also specialized RxNorm utilities beyond simple lookup. `rxnorm_graph.py`, `rxnorm_link.py`, and `graphable.py` suggest support for traversing or rendering RxNorm relationships as a graph, likely to support use cases where understanding drug ingredient/brand/relationship chains matters more than flat code lookup.

7. The repository includes tests for at least SNOMED and RxNorm: `snomed_tests.py` and `rxnorm_tests.py`. That implies the architecture is organized around validating terminology-specific database setup and lookup behavior rather than a single generic test suite.

8. Documentation is generated with Sphinx. The `docs/` folder contains `conf.py`, `index.rst`, and `py-umls.rst`, so the project has a conventional documentation subsystem separate from runtime code. This is useful for understanding public API usage, but it is not part of the runtime data flow.

9. The external dependency boundary is important: UMLS requires a license and data download from official sources, and the repo is designed to consume those local releases rather than calling an external API at runtime. So the main runtime dependency is SQLite and locally installed terminology datasets, not a remote service.

10. Architecturally, this is best drawn as three layers: source terminology files from external vendors, an import/build layer that normalizes them into SQLite, and a lookup/utilities layer that exposes code-to-meaning queries and RxNorm graph/link helpers to downstream Python projects. The repository is intended to be embedded as a submodule or imported package in another application, not deployed as a standalone server.

Main entry points: [`sqlite.py`](https://github.com/chb/py-umls/blob/master/sqlite.py) (SQLite layer), [`rxnorm.py`](https://github.com/chb/py-umls/blob/master/rxnorm.py) (RxNorm lookup), [`snomed.py`](https://github.com/chb/py-umls/blob/master/snomed.py) (SNOMED lookup), [`docs/py-umls.rst`](https://github.com/chb/py-umls/blob/master/docs/py-umls.rst) (API docs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["Source terminologies"]
  node_umls_source["UMLS files<br/>external data"]
  node_snomed_source["SNOMED CT files<br/>external data"]
  node_rxnorm_source["RxNorm files<br/>external data"]
end

subgraph group_build["Import and build"]
  node_umls_sh["UMLS setup<br/>shell import<br/>[umls.sh]"]
  node_rxnorm_sh["RxNorm setup<br/>shell import<br/>[rxnorm.sh]"]
  node_rxnorm_download["RxNorm download<br/>fetch helper<br/>[rxnorm_download.py]"]
  node_csvimporter["CSV importer<br/>load helper<br/>[csvimporter.py]"]
  node_sqlite[("SQLite layer<br/>db access<br/>[sqlite.py]")]
  node_rxnorm_link["RxNorm links<br/>relationship builder<br/>[rxnorm_link.py]"]
  node_rxnorm_link_run["Link runner<br/>pipeline script<br/>[rxnorm_link_run.py]"]
end

subgraph group_runtime["Lookup API"]
  node_umls_api["UMLS lookup<br/>terminology API<br/>[umls.py]"]
  node_snomed_api["SNOMED lookup<br/>terminology API<br/>[snomed.py]"]
  node_rxnorm_api["RxNorm lookup<br/>terminology API<br/>[rxnorm.py]"]
  node_loinc_api["LOINC lookup<br/>terminology API<br/>[loinc.py]"]
  node_rxnorm_graph{{"RxNorm graph<br/>graph utility<br/>[rxnorm_graph.py]"}}
  node_graphable{{"Graphable mixin<br/>graph support<br/>[graphable.py]"}}
  node_package_init["Package init<br/>package root<br/>[__init__.py]"]
end

subgraph group_support["Support"]
  node_snomed_tests["SNOMED tests<br/>test suite<br/>[snomed_tests.py]"]
  node_rxnorm_tests["RxNorm tests<br/>test suite<br/>[rxnorm_tests.py]"]
  node_docs_index["Docs index<br/>documentation<br/>[index.rst]"]
  node_docs_api["API docs<br/>documentation<br/>[py-umls.rst]"]
end

node_umls_source -->|"prepare"| node_umls_sh
node_snomed_source -->|"import"| node_snomed_api
node_rxnorm_source -->|"fetch"| node_rxnorm_download
node_rxnorm_source -->|"prepare"| node_rxnorm_sh
node_umls_sh -->|"load"| node_csvimporter
node_rxnorm_sh -->|"load"| node_csvimporter
node_rxnorm_download -->|"input"| node_csvimporter
node_csvimporter -->|"write"| node_sqlite
node_sqlite -->|"query"| node_umls_api
node_sqlite -->|"query"| node_snomed_api
node_sqlite -->|"query"| node_rxnorm_api
node_sqlite -->|"query"| node_loinc_api
node_rxnorm_api -->|"relationships"| node_rxnorm_link
node_rxnorm_link -->|"build graph"| node_rxnorm_graph
node_graphable -->|"supports"| node_rxnorm_graph
node_rxnorm_link_run -->|"run"| node_rxnorm_link
node_package_init -->|"export"| node_umls_api
node_package_init -->|"export"| node_snomed_api
node_package_init -->|"export"| node_rxnorm_api
node_snomed_tests -->|"validate"| node_snomed_api
node_rxnorm_tests -->|"validate"| node_rxnorm_api
node_rxnorm_tests -->|"validate"| node_rxnorm_graph
node_docs_index -->|"includes"| node_docs_api
node_docs_api -->|"documents"| node_umls_api
node_docs_api -->|"documents"| node_snomed_api
node_docs_api -->|"documents"| node_rxnorm_api

click node_umls_sh "https://github.com/chb/py-umls/blob/master/databases/umls.sh"
click node_rxnorm_sh "https://github.com/chb/py-umls/blob/master/databases/rxnorm.sh"
click node_rxnorm_download "https://github.com/chb/py-umls/blob/master/rxnorm_download.py"
click node_csvimporter "https://github.com/chb/py-umls/blob/master/csvimporter.py"
click node_sqlite "https://github.com/chb/py-umls/blob/master/sqlite.py"
click node_rxnorm_link "https://github.com/chb/py-umls/blob/master/rxnorm_link.py"
click node_rxnorm_link_run "https://github.com/chb/py-umls/blob/master/rxnorm_link_run.py"
click node_umls_api "https://github.com/chb/py-umls/blob/master/umls.py"
click node_snomed_api "https://github.com/chb/py-umls/blob/master/snomed.py"
click node_rxnorm_api "https://github.com/chb/py-umls/blob/master/rxnorm.py"
click node_loinc_api "https://github.com/chb/py-umls/blob/master/loinc.py"
click node_rxnorm_graph "https://github.com/chb/py-umls/blob/master/rxnorm_graph.py"
click node_graphable "https://github.com/chb/py-umls/blob/master/graphable.py"
click node_package_init "https://github.com/chb/py-umls/blob/master/__init__.py"
click node_snomed_tests "https://github.com/chb/py-umls/blob/master/snomed_tests.py"
click node_rxnorm_tests "https://github.com/chb/py-umls/blob/master/rxnorm_tests.py"
click node_docs_index "https://github.com/chb/py-umls/blob/master/docs/index.rst"
click node_docs_api "https://github.com/chb/py-umls/blob/master/docs/py-umls.rst"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_umls_source,node_snomed_source,node_rxnorm_source toneBlue
class node_umls_sh,node_rxnorm_sh,node_rxnorm_download,node_csvimporter,node_sqlite,node_rxnorm_link,node_rxnorm_link_run toneAmber
class node_umls_api,node_snomed_api,node_rxnorm_api,node_loinc_api,node_rxnorm_graph,node_graphable,node_package_init toneMint
class node_snomed_tests,node_rxnorm_tests,node_docs_index,node_docs_api toneRose
```

## Components

### Source terminologies

External terminology releases consumed as local files.

- **UMLS files**: external data · Official UMLS release files used as the local source for imports.
- **SNOMED CT files**: external data · Official SNOMED CT release files used as the local source for imports.
- **RxNorm files**: external data · Official RxNorm release files and derived inputs used by the toolkit.

### Import and build

Scripts and helpers that download, normalize, and load terminology data into SQLite.

- [UMLS setup](https://github.com/chb/py-umls/blob/master/databases/umls.sh): shell import · Shell entrypoint for acquiring and preparing UMLS data. · `databases/umls.sh`
- [RxNorm setup](https://github.com/chb/py-umls/blob/master/databases/rxnorm.sh): shell import · Shell entrypoint for acquiring and preparing RxNorm data. · `databases/rxnorm.sh`
- [RxNorm download](https://github.com/chb/py-umls/blob/master/rxnorm_download.py): fetch helper · Downloads or stages RxNorm inputs before database creation. · `rxnorm_download.py`
- [CSV importer](https://github.com/chb/py-umls/blob/master/csvimporter.py): load helper · Bulk importer for source flat files into SQLite tables. · `csvimporter.py`
- [SQLite layer](https://github.com/chb/py-umls/blob/master/sqlite.py): db access · Shared local database access and query helpers. · `sqlite.py`
- [RxNorm links](https://github.com/chb/py-umls/blob/master/rxnorm_link.py): relationship builder · Builds derived RxNorm relationship/link structures. · `rxnorm_link.py`
- [Link runner](https://github.com/chb/py-umls/blob/master/rxnorm_link_run.py): pipeline script · Command-line runner for the RxNorm link-building pipeline. · `rxnorm_link_run.py`

### Lookup API

User-facing Python modules for querying terminology codes and relationships.

- [UMLS lookup](https://github.com/chb/py-umls/blob/master/umls.py): terminology API · User-facing UMLS lookup class and shell entrypoint. · `umls.py`
- [SNOMED lookup](https://github.com/chb/py-umls/blob/master/snomed.py): terminology API · User-facing SNOMED CT lookup class and shell entrypoint. · `snomed.py`
- [RxNorm lookup](https://github.com/chb/py-umls/blob/master/rxnorm.py): terminology API · User-facing RxNorm lookup class and shell entrypoint. · `rxnorm.py`
- [LOINC lookup](https://github.com/chb/py-umls/blob/master/loinc.py): terminology API · Additional terminology lookup module following the same local-database pattern. · `loinc.py`
- [RxNorm graph](https://github.com/chb/py-umls/blob/master/rxnorm_graph.py): graph utility · Traversal and graph-oriented utilities for RxNorm relationships. · `rxnorm_graph.py`
- [Graphable mixin](https://github.com/chb/py-umls/blob/master/graphable.py): graph support · Shared abstraction for turning terminology relationships into graph-friendly structures. · `graphable.py`
- [Package init](https://github.com/chb/py-umls/blob/master/__init__.py): package root · Top-level package entry for importing the toolkit. · `__init__.py`

### Support

Tests and documentation around the public API.

- [SNOMED tests](https://github.com/chb/py-umls/blob/master/snomed_tests.py): test suite · Behavior tests for SNOMED import and lookup flows. · `snomed_tests.py`
- [RxNorm tests](https://github.com/chb/py-umls/blob/master/rxnorm_tests.py): test suite · Behavior tests for RxNorm import, lookup, and link behavior. · `rxnorm_tests.py`
- [Docs index](https://github.com/chb/py-umls/blob/master/docs/index.rst): documentation · Sphinx documentation entry point and API overview. · `docs/index.rst`
- [API docs](https://github.com/chb/py-umls/blob/master/docs/py-umls.rst): documentation · Generated reference page for the public Python API. · `docs/py-umls.rst`

## Connections

- UMLS files → UMLS setup: prepare · UMLS releases are staged and prepared by the setup script.
- SNOMED CT files → SNOMED lookup: import · SNOMED source files are loaded into the local database used by the lookup API.
- RxNorm files → RxNorm download: fetch · RxNorm source inputs are downloaded or staged first.
- RxNorm files → RxNorm setup: prepare · RxNorm setup script coordinates local preparation of the data release.
- UMLS setup → CSV importer: load · UMLS preparation uses the CSV/flat-file importer.
- RxNorm setup → CSV importer: load · RxNorm preparation uses the CSV/flat-file importer.
- RxNorm download → CSV importer: input · Downloaded RxNorm inputs feed the import pipeline.
- CSV importer → SQLite layer: write · Importer normalizes source files into SQLite tables.
- SQLite layer → UMLS lookup: query · UMLS lookup reads from the shared SQLite database layer.
- SQLite layer → SNOMED lookup: query · SNOMED lookup reads from the shared SQLite database layer.
- SQLite layer → RxNorm lookup: query · RxNorm lookup reads from the shared SQLite database layer.
- SQLite layer → LOINC lookup: query · LOINC lookup follows the same local database access pattern.
- RxNorm lookup → RxNorm links: relationships · RxNorm lookup exposes relationship data used for graph/link building.
- RxNorm links → RxNorm graph: build graph · Derived RxNorm links are shaped into graph traversal structures.
- Graphable mixin → RxNorm graph: supports · Graph-oriented helpers provide a shared abstraction for relationship traversal.
- Link runner → RxNorm links: run · Command-line runner executes the link-building pipeline.
- Package init → UMLS lookup: export · Package root exposes the terminology APIs for importers.
- Package init → SNOMED lookup: export · Package root exposes the terminology APIs for importers.
- Package init → RxNorm lookup: export · Package root exposes the terminology APIs for importers.
- SNOMED tests → SNOMED lookup: validate · Tests exercise SNOMED lookup behavior and database setup.
- RxNorm tests → RxNorm lookup: validate · Tests exercise RxNorm lookup behavior and derived relationship handling.
- RxNorm tests → RxNorm graph: validate · Tests also cover RxNorm graph-related utilities.
- Docs index → API docs: includes · Documentation index points to the public API reference.
- API docs → UMLS lookup: documents · API docs describe the UMLS lookup entrypoint.
- API docs → SNOMED lookup: documents · API docs describe the SNOMED lookup entrypoint.
- API docs → RxNorm lookup: documents · API docs describe the RxNorm lookup entrypoint.
