# elmadervic/medicationsupply architecture

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

- Interactive diagram: https://gitdiagram.com/elmadervic/medicationsupply
- Repository: https://github.com/elmadervic/medicationsupply

## Overview

This repository contains two independent medication-supply research workflows: an R analysis of manufacturing-register coverage and concentration, and a Python substance-level supply analysis. Analysts start from public and manually curated source files, which are standardized into analysis tables and then summarized as concentration, geographic, ATC, and visualization outputs. The graph preserves both branches and their documented major capabilities. Python source excerpts show the build and analysis stages; the R branch’s wiring and outputs are represented from the README, not sampled R source.

Main entry points: [`data/manufacturer-registers/raw`](https://github.com/elmadervic/medicationsupply/tree/main/data/manufacturer-registers/raw) (Register sources), [`supply-analysis/01-data-prep/build_supply.py`](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/01-data-prep/build_supply.py) (Build supply table), [`data/raw`](https://github.com/elmadervic/medicationsupply/tree/main/data/raw) (Raw snapshots), [`data/interim/supply_long.csv`](https://github.com/elmadervic/medicationsupply/blob/main/data/interim/supply_long.csv) (Long supply table)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Source data"]
  node_public_sources["Public sources"]
  node_register_sources["Register sources"]
  node_raw_data["Raw snapshots"]
end

subgraph group_registers["Register analysis"]
  node_combine_registers["Combine registers"]
  node_combined_table["Combined register table"]
  node_register_hhi["Register concentration<br/>[HHI_V2.R]"]
  node_api_diversification["API diversification"]
  node_register_plots["Register plots"]
  node_register_summary["ATC country summary"]
end

subgraph group_supply["Supply analysis"]
  node_fetch["Fetch snapshots<br/>[fetch.py]"]
  node_inspect["Inspect sources<br/>[inspect_sources.py]"]
  node_build_supply["Build supply table<br/>[build_supply.py]"]
  node_interim_table["Long supply table<br/>[supply_long.csv]"]
  node_analyse["Supply summaries<br/>[analyse.py]"]
  node_supply_outputs["Supply result tables"]
  node_plots["Supply visualizations<br/>[plots.py]"]
  node_qc["Quality checks<br/>[qc.py]"]
end

subgraph group_shared["Shared analysis"]
  node_normalization["Name normalization<br/>[normalize.py]"]
  node_country_resolution["Country resolution<br/>[countries.py]"]
  node_atc_lookup["ATC mapping<br/>[atc.py]"]
  node_ulcm_reader["Critical list reader<br/>[ulcm.py]"]
end

node_analyst(("Research analyst"))
node_external(("Source services"))

node_analyst -->|"starts snapshot"| node_fetch
node_external -->|"provides downloads"| node_fetch
node_fetch -->|"writes snapshots"| node_raw_data
node_analyst -->|"inspects inputs"| node_inspect
node_inspect -->|"reads files"| node_raw_data
node_register_sources -->|"provides registers"| node_combine_registers
node_combine_registers -->|"writes table"| node_combined_table
node_register_sources -->|"provides registers"| node_register_hhi
node_register_hhi -->|"writes results"| node_combined_table
node_register_sources -->|"provides registers"| node_api_diversification
node_register_sources -->|"provides registers"| node_register_plots
node_combined_table -->|"reads table"| node_register_plots
node_register_sources -->|"provides registers"| node_register_summary
node_raw_data -->|"provides sources"| node_build_supply
node_build_supply -->|"normalizes names"| node_normalization
node_build_supply -->|"resolves countries"| node_country_resolution
node_build_supply -->|"looks up codes"| node_atc_lookup
node_register_sources -.->|"optional ATC input"| node_atc_lookup
node_build_supply -->|"writes rows"| node_interim_table
node_interim_table -->|"reads rows"| node_analyse
node_raw_data -->|"provides critical list"| node_ulcm_reader
node_analyse -->|"loads universe"| node_ulcm_reader
node_analyse -->|"writes summaries"| node_supply_outputs
node_supply_outputs -->|"loads results"| node_plots
node_interim_table -->|"loads supply rows"| node_plots
node_interim_table -->|"checks rows"| node_qc
node_supply_outputs -->|"checks results"| node_qc
node_raw_data -->|"checks snapshot"| node_qc

click node_public_sources "https://github.com/elmadervic/medicationsupply/tree/main/data/raw"
click node_register_sources "https://github.com/elmadervic/medicationsupply/tree/main/data/manufacturer-registers/raw"
click node_fetch "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/01-data-prep/fetch.py"
click node_inspect "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/01-data-prep/inspect_sources.py"
click node_combine_registers "https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/01-data-prep/ComebineAll4SourcesV2.R"
click node_combined_table "https://github.com/elmadervic/medicationsupply/tree/main/data/manufacturer-registers/out"
click node_register_hhi "https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/02-analysis/HHI_V2.R"
click node_api_diversification "https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/02-analysis/api_diversification_by_source.R"
click node_register_plots "https://github.com/elmadervic/medicationsupply/tree/main/manufacturer-registers/03-figures"
click node_register_summary "https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/03-figures/summaryCodeNameCountry_V2.R"
click node_raw_data "https://github.com/elmadervic/medicationsupply/tree/main/data/raw"
click node_build_supply "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/01-data-prep/build_supply.py"
click node_normalization "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/normalize.py"
click node_country_resolution "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/countries.py"
click node_atc_lookup "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/atc.py"
click node_ulcm_reader "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/ulcm.py"
click node_interim_table "https://github.com/elmadervic/medicationsupply/blob/main/data/interim/supply_long.csv"
click node_analyse "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/02-analysis/analyse.py"
click node_supply_outputs "https://github.com/elmadervic/medicationsupply/tree/main/data/out"
click node_plots "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/03-figures/plots.py"
click node_qc "https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/02-analysis/qc.py"

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_public_sources,node_register_sources,node_raw_data toneBlue
class node_combine_registers,node_combined_table,node_register_hhi,node_api_diversification,node_register_plots,node_register_summary toneAmber
class node_fetch,node_inspect,node_build_supply,node_interim_table,node_analyse,node_supply_outputs,node_plots,node_qc toneMint
class node_normalization,node_country_resolution,node_atc_lookup,node_ulcm_reader toneRose
class node_analyst,node_external toneIndigo
```

## Components

### Source data

- [Public sources](https://github.com/elmadervic/medicationsupply/tree/main/data/raw): `data/raw`
- [Register sources](https://github.com/elmadervic/medicationsupply/tree/main/data/manufacturer-registers/raw): `data/manufacturer-registers/raw`
- [Raw snapshots](https://github.com/elmadervic/medicationsupply/tree/main/data/raw): `data/raw`

### Register analysis

- [Combine registers](https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/01-data-prep/ComebineAll4SourcesV2.R): `manufacturer-registers/01-data-prep/ComebineAll4SourcesV2.R`
- [Combined register table](https://github.com/elmadervic/medicationsupply/tree/main/data/manufacturer-registers/out): `data/manufacturer-registers/out`
- [Register concentration](https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/02-analysis/HHI_V2.R): `manufacturer-registers/02-analysis/HHI_V2.R`
- [API diversification](https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/02-analysis/api_diversification_by_source.R): `manufacturer-registers/02-analysis/api_diversification_by_source.R`
- [Register plots](https://github.com/elmadervic/medicationsupply/tree/main/manufacturer-registers/03-figures): `manufacturer-registers/03-figures`
- [ATC country summary](https://github.com/elmadervic/medicationsupply/blob/main/manufacturer-registers/03-figures/summaryCodeNameCountry_V2.R): `manufacturer-registers/03-figures/summaryCodeNameCountry_V2.R`

### Supply analysis

- [Fetch snapshots](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/01-data-prep/fetch.py): `supply-analysis/01-data-prep/fetch.py`
- [Inspect sources](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/01-data-prep/inspect_sources.py): `supply-analysis/01-data-prep/inspect_sources.py`
- [Build supply table](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/01-data-prep/build_supply.py): `supply-analysis/01-data-prep/build_supply.py`
- [Long supply table](https://github.com/elmadervic/medicationsupply/blob/main/data/interim/supply_long.csv): `data/interim/supply_long.csv`
- [Supply summaries](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/02-analysis/analyse.py): `supply-analysis/02-analysis/analyse.py`
- [Supply result tables](https://github.com/elmadervic/medicationsupply/tree/main/data/out): `data/out`
- [Supply visualizations](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/03-figures/plots.py): `supply-analysis/03-figures/plots.py`
- [Quality checks](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/02-analysis/qc.py): `supply-analysis/02-analysis/qc.py`

### Shared analysis

- [Name normalization](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/normalize.py): `supply-analysis/common/normalize.py`
- [Country resolution](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/countries.py): `supply-analysis/common/countries.py`
- [ATC mapping](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/atc.py): `supply-analysis/common/atc.py`
- [Critical list reader](https://github.com/elmadervic/medicationsupply/blob/main/supply-analysis/common/ulcm.py): `supply-analysis/common/ulcm.py`

### Other components

- **Research analyst**
- **Source services**

## Connections

- Research analyst → Fetch snapshots: starts snapshot
- Source services → Fetch snapshots: provides downloads
- Fetch snapshots → Raw snapshots: writes snapshots
- Research analyst → Inspect sources: inspects inputs
- Inspect sources → Raw snapshots: reads files
- Register sources → Combine registers: provides registers
- Combine registers → Combined register table: writes table
- Register sources → Register concentration: provides registers
- Register concentration → Combined register table: writes results
- Register sources → API diversification: provides registers
- Register sources → Register plots: provides registers
- Combined register table → Register plots: reads table
- Register sources → ATC country summary: provides registers
- Raw snapshots → Build supply table: provides sources
- Build supply table → Name normalization: normalizes names
- Build supply table → Country resolution: resolves countries
- Build supply table → ATC mapping: looks up codes
- Register sources → ATC mapping: optional ATC input
- Build supply table → Long supply table: writes rows
- Long supply table → Supply summaries: reads rows
- Raw snapshots → Critical list reader: provides critical list
- Supply summaries → Critical list reader: loads universe
- Supply summaries → Supply result tables: writes summaries
- Supply result tables → Supply visualizations: loads results
- Long supply table → Supply visualizations: loads supply rows
- Long supply table → Quality checks: checks rows
- Supply result tables → Quality checks: checks results
- Raw snapshots → Quality checks: checks snapshot