# khaeru/sdmx architecture

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

- Interactive diagram: https://gitdiagram.com/khaeru/sdmx
- Repository: https://github.com/khaeru/sdmx

## Overview

sdmx implements SDMX 2.1/3.0 exchange: users query provider services or read files, parse responses into messages and information-model objects, then write interchange formats or convert data to pandas. Provider adapters and REST URL construction customize retrieval; readers dispatch by media type to format-specific parsers. The graph preserves both the retrieval and file-conversion branches, plus model and output layers. Relationships are limited to README claims and source references shown in the index or excerpts; unsampled implementation details are not asserted.

Main entry points: [`sdmx/message.py`](https://github.com/khaeru/sdmx/blob/main/sdmx/message.py) (Messages), [`sdmx/client.py`](https://github.com/khaeru/sdmx/blob/main/sdmx/client.py) (Client retrieval), [`sdmx/reader/base.py`](https://github.com/khaeru/sdmx/blob/main/sdmx/reader/base.py) (Reader dispatch), [`sdmx/model/common.py`](https://github.com/khaeru/sdmx/blob/main/sdmx/model/common.py) (Core information model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and providers"]
  node_client["Client retrieval<br/>[client.py]"]
  node_sources["Provider adapters"]
  node_rest["REST requests<br/>[common.py]"]
  node_session["HTTP session<br/>[session.py]"]
end

subgraph group_formats["Parsing and serialization"]
  node_dispatch["Reader dispatch<br/>[base.py]"]
  node_xmlread["XML readers"]
  node_jsonread["JSON reader<br/>[json.py]"]
  node_csvread["CSV reader<br/>[csv.py]"]
  node_formattypes["Media types<br/>[__init__.py]"]
  node_csvformat["CSV formats<br/>[common.py]"]
end

subgraph group_domain["SDMX domain"]
  node_message["Messages<br/>[message.py]"]
  node_commonmodel["Core information model<br/>[common.py]"]
  node_model21["SDMX 2.1 model<br/>[v21.py]"]
  node_model30["SDMX 3.0 model<br/>[v30.py]"]
end

subgraph group_outputs["Conversion and output"]
  node_pandas["Pandas conversion<br/>[pandas.py]"]
  node_csvwrite["CSV writer<br/>[csv.py]"]
  node_xmlwrite["XML writer<br/>[xml.py]"]
end

node_user(("Python user"))
node_http{{"SDMX services"}}
node_fileuser(("File consumer"))

node_user -->|"queries"| node_client
node_user -->|"reads files"| node_dispatch
node_client -->|"selects provider"| node_sources
node_client -->|"builds request"| node_rest
node_client -->|"sends request"| node_session
node_session -->|"requests data"| node_http
node_client -->|"parses response"| node_dispatch
node_dispatch -->|"matches media type"| node_formattypes
node_dispatch -->|"produces"| node_message
node_xmlread -->|"builds messages"| node_message
node_jsonread -->|"builds messages"| node_message
node_csvread -->|"builds messages"| node_message
node_csvread -->|"uses options"| node_csvformat
node_message -->|"uses model"| node_commonmodel
node_message -->|"uses model"| node_model21
node_message -->|"uses model"| node_model30
node_commonmodel -->|"provides base classes"| node_model21
node_commonmodel -->|"provides base classes"| node_model30
node_user -->|"converts data"| node_pandas
node_pandas -->|"converts from"| node_message
node_user -->|"writes CSV"| node_csvwrite
node_csvwrite -->|"uses conversion"| node_pandas
node_user -->|"writes XML"| node_xmlwrite
node_xmlwrite -->|"serializes"| node_message
node_csvwrite -->|"outputs file format"| node_fileuser
node_xmlwrite -->|"outputs file format"| node_fileuser

click node_client "https://github.com/khaeru/sdmx/blob/main/sdmx/client.py"
click node_sources "https://github.com/khaeru/sdmx/tree/main/sdmx/source"
click node_rest "https://github.com/khaeru/sdmx/blob/main/sdmx/rest/common.py"
click node_session "https://github.com/khaeru/sdmx/blob/main/sdmx/session.py"
click node_dispatch "https://github.com/khaeru/sdmx/blob/main/sdmx/reader/base.py"
click node_xmlread "https://github.com/khaeru/sdmx/tree/main/sdmx/reader/xml"
click node_jsonread "https://github.com/khaeru/sdmx/blob/main/sdmx/reader/json.py"
click node_csvread "https://github.com/khaeru/sdmx/blob/main/sdmx/reader/csv.py"
click node_formattypes "https://github.com/khaeru/sdmx/blob/main/sdmx/format/__init__.py"
click node_csvformat "https://github.com/khaeru/sdmx/blob/main/sdmx/format/csv/common.py"
click node_message "https://github.com/khaeru/sdmx/blob/main/sdmx/message.py"
click node_commonmodel "https://github.com/khaeru/sdmx/blob/main/sdmx/model/common.py"
click node_model21 "https://github.com/khaeru/sdmx/blob/main/sdmx/model/v21.py"
click node_model30 "https://github.com/khaeru/sdmx/blob/main/sdmx/model/v30.py"
click node_pandas "https://github.com/khaeru/sdmx/blob/main/sdmx/convert/pandas.py"
click node_csvwrite "https://github.com/khaeru/sdmx/blob/main/sdmx/writer/csv.py"
click node_xmlwrite "https://github.com/khaeru/sdmx/blob/main/sdmx/writer/xml.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_client,node_sources,node_rest,node_session,node_user toneBlue
class node_dispatch,node_xmlread,node_jsonread,node_csvread,node_formattypes,node_csvformat toneAmber
class node_message,node_commonmodel,node_model21,node_model30 toneMint
class node_pandas,node_csvwrite,node_xmlwrite toneRose
class node_http,node_fileuser toneIndigo
```

## Components

### Access and providers

- [Client retrieval](https://github.com/khaeru/sdmx/blob/main/sdmx/client.py): `sdmx/client.py`
- [Provider adapters](https://github.com/khaeru/sdmx/tree/main/sdmx/source): `sdmx/source`
- [REST requests](https://github.com/khaeru/sdmx/blob/main/sdmx/rest/common.py): `sdmx/rest/common.py`
- [HTTP session](https://github.com/khaeru/sdmx/blob/main/sdmx/session.py): `sdmx/session.py`

### Parsing and serialization

- [Reader dispatch](https://github.com/khaeru/sdmx/blob/main/sdmx/reader/base.py): `sdmx/reader/base.py`
- [XML readers](https://github.com/khaeru/sdmx/tree/main/sdmx/reader/xml): `sdmx/reader/xml`
- [JSON reader](https://github.com/khaeru/sdmx/blob/main/sdmx/reader/json.py): `sdmx/reader/json.py`
- [CSV reader](https://github.com/khaeru/sdmx/blob/main/sdmx/reader/csv.py): `sdmx/reader/csv.py`
- [Media types](https://github.com/khaeru/sdmx/blob/main/sdmx/format/__init__.py): `sdmx/format/__init__.py`
- [CSV formats](https://github.com/khaeru/sdmx/blob/main/sdmx/format/csv/common.py): `sdmx/format/csv/common.py`

### SDMX domain

- [Messages](https://github.com/khaeru/sdmx/blob/main/sdmx/message.py): `sdmx/message.py`
- [Core information model](https://github.com/khaeru/sdmx/blob/main/sdmx/model/common.py): `sdmx/model/common.py`
- [SDMX 2.1 model](https://github.com/khaeru/sdmx/blob/main/sdmx/model/v21.py): `sdmx/model/v21.py`
- [SDMX 3.0 model](https://github.com/khaeru/sdmx/blob/main/sdmx/model/v30.py): `sdmx/model/v30.py`

### Conversion and output

- [Pandas conversion](https://github.com/khaeru/sdmx/blob/main/sdmx/convert/pandas.py): `sdmx/convert/pandas.py`
- [CSV writer](https://github.com/khaeru/sdmx/blob/main/sdmx/writer/csv.py): `sdmx/writer/csv.py`
- [XML writer](https://github.com/khaeru/sdmx/blob/main/sdmx/writer/xml.py): `sdmx/writer/xml.py`

### Other components

- **Python user**
- **SDMX services**
- **File consumer**

## Connections

- Python user → Client retrieval: queries
- Python user → Reader dispatch: reads files
- Client retrieval → Provider adapters: selects provider (evidence: `sdmx/client.py`)
- Client retrieval → REST requests: builds request (evidence: `sdmx/client.py`)
- Client retrieval → HTTP session: sends request (evidence: `sdmx/client.py`)
- HTTP session → SDMX services: requests data
- Client retrieval → Reader dispatch: parses response (evidence: `sdmx/client.py`)
- Reader dispatch → Media types: matches media type (evidence: `sdmx/reader/base.py`)
- Reader dispatch → Messages: produces (evidence: `sdmx/reader/base.py`)
- XML readers → Messages: builds messages (evidence: `sdmx/reader/xml/common.py`)
- JSON reader → Messages: builds messages (evidence: `sdmx/reader/json.py`)
- CSV reader → Messages: builds messages (evidence: `sdmx/reader/csv.py`)
- CSV reader → CSV formats: uses options (evidence: `sdmx/reader/csv.py`)
- Messages → Core information model: uses model (evidence: `sdmx/message.py`)
- Messages → SDMX 2.1 model: uses model (evidence: `sdmx/message.py`)
- Messages → SDMX 3.0 model: uses model (evidence: `sdmx/message.py`)
- Core information model → SDMX 2.1 model: provides base classes (evidence: `sdmx/model/v21.py`)
- Core information model → SDMX 3.0 model: provides base classes (evidence: `sdmx/model/v30.py`)
- Python user → Pandas conversion: converts data
- Pandas conversion → Messages: converts from (evidence: `sdmx/convert/pandas.py`)
- Python user → CSV writer: writes CSV
- CSV writer → Pandas conversion: uses conversion (evidence: `sdmx/writer/csv.py`)
- Python user → XML writer: writes XML
- XML writer → Messages: serializes (evidence: `sdmx/writer/xml.py`)
- CSV writer → File consumer: outputs file format
- XML writer → File consumer: outputs file format
