# datasets/harmonized-system architecture

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

- Interactive diagram: https://gitdiagram.com/datasets/harmonized-system
- Repository: https://github.com/datasets/harmonized-system

## Overview

This repository packages Harmonized System commodity classifications as data, rather than running a classification service. Its main use is to consume the published classification tables; the included converter separately turns UN Comtrade JSON into CSV rows with section, code, description, parent, and level fields. The README identifies UN Comtrade as the dataset source. The converter accepts arbitrary input and output filenames, so its output is not linked to a particular checked-in CSV.

Main entry points: [`scripts/convert.py`](https://github.com/datasets/harmonized-system/blob/main/scripts/convert.py) (JSON-to-CSV converter), [`data/harmonized-system.csv`](https://github.com/datasets/harmonized-system/blob/main/data/harmonized-system.csv) (HS classifications), [`data/sections.csv`](https://github.com/datasets/harmonized-system/blob/main/data/sections.csv) (HS sections), [`datapackage.json`](https://github.com/datasets/harmonized-system/blob/main/datapackage.json) (Package metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dataset["Classification data"]
  node_hsdata["HS classifications"]
  node_sections["HS sections<br/>[sections.csv]"]
  node_metadata["Package metadata<br/>[datapackage.json]"]
end

subgraph group_conversion["Conversion utility"]
  node_converter["JSON-to-CSV converter<br/>[convert.py]"]
end

node_consumer(("Dataset consumer"))
node_comtrade["UN Comtrade JSON"]
node_csvoutput["CSV output"]

node_consumer -->|"reads classifications"| node_hsdata
node_consumer -->|"reads sections"| node_sections
node_consumer -->|"reads metadata"| node_metadata
node_comtrade -->|"provides JSON"| node_converter
node_converter -->|"writes CSV"| node_csvoutput

click node_hsdata "https://github.com/datasets/harmonized-system/blob/main/data/harmonized-system.csv"
click node_sections "https://github.com/datasets/harmonized-system/blob/main/data/sections.csv"
click node_metadata "https://github.com/datasets/harmonized-system/blob/main/datapackage.json"
click node_converter "https://github.com/datasets/harmonized-system/blob/main/scripts/convert.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_hsdata,node_sections,node_metadata toneBlue
class node_converter toneAmber
class node_consumer,node_comtrade,node_csvoutput toneIndigo
```

## Components

### Classification data

- [HS classifications](https://github.com/datasets/harmonized-system/blob/main/data/harmonized-system.csv): `data/harmonized-system.csv`
- [HS sections](https://github.com/datasets/harmonized-system/blob/main/data/sections.csv): `data/sections.csv`
- [Package metadata](https://github.com/datasets/harmonized-system/blob/main/datapackage.json): `datapackage.json`

### Conversion utility

- [JSON-to-CSV converter](https://github.com/datasets/harmonized-system/blob/main/scripts/convert.py): `scripts/convert.py`

### Other components

- **Dataset consumer**
- **UN Comtrade JSON**
- **CSV output**

## Connections

- Dataset consumer → HS classifications: reads classifications
- Dataset consumer → HS sections: reads sections
- Dataset consumer → Package metadata: reads metadata
- UN Comtrade JSON → JSON-to-CSV converter: provides JSON
- JSON-to-CSV converter → CSV output: writes CSV